diff --git a/BUILD.md b/BUILD.md index cbe66cdbe7..6a9d58e7e2 100644 --- a/BUILD.md +++ b/BUILD.md @@ -572,3 +572,11 @@ See "Available System Integrations" in `zig build -h` to see available system in `zig build --system deps_dir` will enable all integrations and turn off dependency fetching. This requires you to pre-download the dependencies which don't have a system integration into `deps_dir` (at the time of writing these are ziglua, [`lua_dev_deps`](https://github.com/neovim/deps/blob/master/opt/lua-dev-deps.tar.gz), and the built-in tree-sitter parsers). You have to create subdirectories whose names are the respective package's hash under `deps_dir` and unpack the dependencies inside that directory - ziglua should go under `deps_dir/zlua-0.1.0-hGRpC1dCBQDf-IqqUifYvyr8B9-4FlYXqY8cl7HIetrC` and so on. Hashes should be taken from `build.zig.zon`. See the `prepare` function of [this `PKGBUILD`](https://git.sr.ht/~chinmay/nvim_build/tree/26364a4cf9b4819f52a3e785fa5a43285fb9cea2/item/PKGBUILD#L90) for an example. + +## Cross-compiling + +Cross-compilation is not supported, but we collect notes here for reference (improvements welcome). +Also relevant for webassembly (WASM) build. + +- Set `NVIM_HOST_PRG` so that the docs and tags generation works without + depending on the target binary. diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 8abc4dcb84..3b9c98a343 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -39,6 +39,10 @@ effects. Be careful not to destroy your text. ============================================================================== 2. Defining autocommands *autocmd-define* +Use |nvim_create_autocmd()| to define an event handler from Lua. + +Vimscript commands are described below. + *:au* *:autocmd* :au[tocmd] [group] {event} {aupat} [++once] [++nested] {cmd} Add {cmd} to the list of commands that Vim will @@ -125,6 +129,14 @@ prompt. When one command outputs two messages this can happen anyway. ============================================================================== 3. Removing autocommands *autocmd!* *autocmd-remove* +Using Lua, these functions remove autocmds and autocmd groups: + +- |nvim_del_autocmd()| +- |nvim_del_augroup_by_id()| +- |nvim_del_augroup_by_name()| + +Vimscript commands are described below. + :au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd} Remove all autocommands associated with {event} and {aupat}, and add the command {cmd}. @@ -1118,8 +1130,8 @@ TermResponse When Nvim receives a DA1, OSC, DCS, or APC response from -- (red) using OSC 4 vim.api.nvim_create_autocmd('TermResponse', { once = true, - callback = function(args) - local resp = args.data.sequence + callback = function(ev) + local resp = ev.data.sequence local r, g, b = resp:match("\027%]4;1;rgb:(%w+)/(%w+)/(%w+)") end, }) diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index ee2d1ff45a..386e6bd3ae 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1432,10 +1432,6 @@ gq{motion} Format the lines that {motion} moves over. formatting |fo-table|. The cursor is left on the first non-blank of the last formatted line. - NOTE: The "Q" command formerly performed this - function. If you still want to use "Q" for - formatting, use this mapping: > - :nnoremap Q gq gqgq *gqgq* *gqq* gqq Format the current line. With a count format that diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 19055c08e5..fe34363aca 100644 --- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -182,14 +182,13 @@ except only the last section of the buffer is editable, and the user can - advanced "picker" plugins A prompt buffer is created by setting 'buftype' to "prompt". You would -normally only do that in a newly created buffer: >vim +normally only do that in a new, empty buffer: >vim :set buftype=prompt -Prompt buffers ignore modified checks for changes made to the buffer, so -interactive input does not make them hard to close. But if a plugin or user -explicitly sets 'modified', a modified prompt buffer can't be closed without -saving. +Prompt buffers do not implicitly set 'modified' on user input or other +changes. But a user or plugin can set 'modified' explicitly, to prevent the +buffer from being easily closed. The user can edit and input text at the end of the buffer. Pressing Enter in the input section invokes the |prompt_setcallback()| callback, which is diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 9628b704df..aeafb8e4c6 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -425,8 +425,8 @@ DiagnosticChanged After diagnostics have changed. When used from Lua, Example: >lua vim.api.nvim_create_autocmd('DiagnosticChanged', { - callback = function(args) - local diagnostics = args.data.diagnostics + callback = function(ev) + local diagnostics = ev.data.diagnostics vim.print(diagnostics) end, }) diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 5a6a16dcab..a64d70ac56 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -107,7 +107,7 @@ BUFFER-LOCAL DEFAULTS - |K| is mapped to |vim.lsp.buf.hover()| unless 'keywordprg' is customized or a custom keymap for `K` exists. - Document colors are enabled for highlighting color references in a document. - - To opt out call `vim.lsp.document_color.enable(false, args.buf)` on |LspAttach|. + - To opt out call `vim.lsp.document_color.enable(false, ev.buf)` on |LspAttach|. DISABLING DEFAULTS *lsp-defaults-disable* @@ -117,15 +117,15 @@ You can remove GLOBAL keymaps at any time using |vim.keymap.del()| or To remove or override BUFFER-LOCAL defaults, define a |LspAttach| handler: >lua vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) + callback = function(ev) -- Unset 'formatexpr' - vim.bo[args.buf].formatexpr = nil + vim.bo[ev.buf].formatexpr = nil -- Unset 'omnifunc' - vim.bo[args.buf].omnifunc = nil + vim.bo[ev.buf].omnifunc = nil -- Unmap K - vim.keymap.del('n', 'K', { buffer = args.buf }) + vim.keymap.del('n', 'K', { buffer = ev.buf }) -- Disable document colors - vim.lsp.document_color.enable(false, args.buf) + vim.lsp.document_color.enable(false, ev.buf) end, }) < @@ -257,8 +257,8 @@ Example: Enable auto-completion and auto-formatting ("linting"): >lua vim.api.nvim_create_autocmd('LspAttach', { group = vim.api.nvim_create_augroup('my.lsp', {}), - callback = function(args) - local client = assert(vim.lsp.get_client_by_id(args.data.client_id)) + callback = function(ev) + local client = assert(vim.lsp.get_client_by_id(ev.data.client_id)) if client:supports_method('textDocument/implementation') then -- Create a keymap for vim.lsp.buf.implementation ... end @@ -269,7 +269,7 @@ Example: Enable auto-completion and auto-formatting ("linting"): >lua -- local chars = {}; for i = 32, 126 do table.insert(chars, string.char(i)) end -- client.server_capabilities.completionProvider.triggerCharacters = chars - vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true}) + vim.lsp.completion.enable(true, client.id, ev.buf, {autotrigger = true}) end -- Auto-format ("lint") on save. @@ -278,9 +278,9 @@ Example: Enable auto-completion and auto-formatting ("linting"): >lua and client:supports_method('textDocument/formatting') then vim.api.nvim_create_autocmd('BufWritePre', { group = vim.api.nvim_create_augroup('my.lsp', {clear=false}), - buffer = args.buf, + buffer = ev.buf, callback = function() - vim.lsp.buf.format({ bufnr = args.buf, id = client.id, timeout_ms = 1000 }) + vim.lsp.buf.format({ bufnr = ev.buf, id = client.id, timeout_ms = 1000 }) end, }) end @@ -615,15 +615,15 @@ LspDetach *LspDetach* Example: >lua vim.api.nvim_create_autocmd('LspDetach', { - callback = function(args) + callback = function(ev) -- Get the detaching client - local client = vim.lsp.get_client_by_id(args.data.client_id) + local client = vim.lsp.get_client_by_id(ev.data.client_id) -- Remove the autocommand to format the buffer on save, if it exists if client:supports_method('textDocument/formatting') then vim.api.nvim_clear_autocmds({ event = 'BufWritePre', - buffer = args.buf, + buffer = ev.buf, }) end end, @@ -639,11 +639,11 @@ LspNotify *LspNotify* Example: >lua vim.api.nvim_create_autocmd('LspNotify', { - callback = function(args) - local bufnr = args.buf - local client_id = args.data.client_id - local method = args.data.method - local params = args.data.params + callback = function(ev) + local bufnr = ev.buf + local client_id = ev.data.client_id + local method = ev.data.method + local params = ev.data.params -- do something with the notification if method == 'textDocument/...' then @@ -704,11 +704,11 @@ LspRequest *LspRequest* Example: >lua vim.api.nvim_create_autocmd('LspRequest', { - callback = function(args) - local bufnr = args.buf - local client_id = args.data.client_id - local request_id = args.data.request_id - local request = args.data.request + callback = function(ev) + local bufnr = ev.buf + local client_id = ev.data.client_id + local request_id = ev.data.request_id + local request = ev.data.request if request.type == 'pending' then -- do something with pending requests track_pending(client_id, bufnr, request_id, request) @@ -733,11 +733,11 @@ LspTokenUpdate *LspTokenUpdate* Example: >lua vim.api.nvim_create_autocmd('LspTokenUpdate', { - callback = function(args) - local token = args.data.token + callback = function(ev) + local token = ev.data.token if token.type == 'variable' and not token.modifiers.readonly then vim.lsp.semantic_tokens.highlight_token( - token, args.buf, args.data.client_id, 'MyMutableVariableHighlight' + token, ev.buf, ev.data.client_id, 'MyMutableVariableHighlight' ) end end, @@ -1045,9 +1045,9 @@ foldclose({kind}, {winid}) *vim.lsp.foldclose()* To automatically fold imports when opening a file, you can use an autocmd: >lua vim.api.nvim_create_autocmd('LspNotify', { - callback = function(args) - if args.data.method == 'textDocument/didOpen' then - vim.lsp.foldclose('imports', vim.fn.bufwinid(args.buf)) + callback = function(ev) + if ev.data.method == 'textDocument/didOpen' then + vim.lsp.foldclose('imports', vim.fn.bufwinid(ev.buf)) end end, }) @@ -1078,8 +1078,8 @@ foldexpr({lnum}) *vim.lsp.foldexpr()* vim.o.foldexpr = 'v:lua.vim.treesitter.foldexpr()' -- Prefer LSP folding if client supports it vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - local client = vim.lsp.get_client_by_id(args.data.client_id) + callback = function(ev) + local client = vim.lsp.get_client_by_id(ev.data.client_id) if client:supports_method('textDocument/foldingRange') then local win = vim.api.nvim_get_current_win() vim.wo[win][0].foldexpr = 'v:lua.vim.lsp.foldexpr()' @@ -2437,8 +2437,8 @@ enable({enable}, {filter}) *vim.lsp.on_type_formatting.enable()* -- Enable for a specific client vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - local client_id = args.data.client_id + callback = function(ev) + local client_id = ev.data.client_id local client = assert(vim.lsp.get_client_by_id(client_id)) if client.name == 'rust-analyzer' then vim.lsp.on_type_formatting.enable(true, { client_id = client_id }) @@ -2629,11 +2629,11 @@ highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts}) use inside |LspTokenUpdate| callbacks. Parameters: ~ - • {token} (`table`) A semantic token, found as `args.data.token` in + • {token} (`table`) Semantic token, provided as `ev.data.token` in |LspTokenUpdate| - • {bufnr} (`integer`) The buffer to highlight, or `0` for current - buffer - • {client_id} (`integer`) The ID of the |vim.lsp.Client| + • {bufnr} (`integer`) Buffer to highlight, or `0` for current + buffer. + • {client_id} (`integer`) ID of the |vim.lsp.Client| • {hl_group} (`string`) Highlight group name • {opts} (`table?`) Optional parameters: • {priority}? (`integer`, default: diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index d5d4112ff1..776126b667 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -536,8 +536,8 @@ For example, this allows you to set buffer-local mappings for some filetypes: >lua vim.api.nvim_create_autocmd("FileType", { pattern = "lua", - callback = function(args) - vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf }) + callback = function(ev) + vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = ev.buf }) end }) < diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 4dc3057afe..f40a4ee622 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -4468,11 +4468,13 @@ A jump table for the options with a short description can be found at |Q_op|. result of a BufNewFile, BufRead/BufReadPost, BufWritePost, FileAppendPost or VimLeave autocommand event. See |gzip-example| for an explanation. + + When 'buftype' is "prompt", 'modified' is not implicitly set when the + buffer is changed, but a user or plugin may explicitly set it. + When 'buftype' is "nowrite" or "nofile", this option may be set, but - it is ignored and will not block closing the window. For "prompt" - buffers, changes made to the buffer do not make it count as modified, - but an explicit ":set modified" is respected and will block closing the - window. + will be ignored. + Note that the text may actually be the same, e.g. 'modified' is set when using "rA" on an "A". diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt index 0f337fba8f..2ee92499ae 100644 --- a/runtime/doc/terminal.txt +++ b/runtime/doc/terminal.txt @@ -226,10 +226,10 @@ from a |TermRequest| handler: >lua }) local ns = vim.api.nvim_create_namespace('my.terminal.prompt') vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - if string.match(args.data.sequence, '^\027]133;A') then - local lnum = args.data.cursor[1] - vim.api.nvim_buf_set_extmark(args.buf, ns, lnum - 1, 0, { + callback = function(ev) + if string.match(ev.data.sequence, '^\027]133;A') then + local lnum = ev.data.cursor[1] + vim.api.nvim_buf_set_extmark(ev.buf, ns, lnum - 1, 0, { sign_text = '▶', sign_hl_group = 'SpecialChar', }) diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 7f2ee6452b..38f275766f 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -1165,9 +1165,9 @@ start({bufnr}, {lang}) *vim.treesitter.start()* Example: >lua vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', - callback = function(args) - vim.treesitter.start(args.buf, 'latex') - vim.bo[args.buf].syntax = 'ON' -- only if additional legacy syntax is needed + callback = function(ev) + vim.treesitter.start(ev.buf, 'latex') + vim.bo[ev.buf].syntax = 'ON' -- only if additional legacy syntax is needed end }) < diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 01472b04c0..72efe5abd0 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -587,8 +587,8 @@ bufadd({name}) *bufadd()* (`integer`) bufexists({buf}) *bufexists()* - The result is a Number, which is |TRUE| if a buffer called - {buf} exists. + Checks whether a buffer with the name or number {buf} exists. + Returns |TRUE| if the buffer exists, |FALSE| otherwise. If the {buf} argument is a number, buffer numbers are used. Number zero is the alternate buffer for the current window. @@ -615,8 +615,9 @@ bufexists({buf}) *bufexists()* (`0|1`) buflisted({buf}) *buflisted()* - The result is a Number, which is |TRUE| if a buffer called - {buf} exists and is listed (has the 'buflisted' option set). + Checks whether a buffer called {buf} exists and is listed + (has the 'buflisted' option set). Returns |TRUE| if so, + |FALSE| otherwise. The {buf} argument is used like with |bufexists()|. Parameters: ~ @@ -639,8 +640,9 @@ bufload({buf}) *bufload()* • {buf} (`any`) bufloaded({buf}) *bufloaded()* - The result is a Number, which is |TRUE| if a buffer called - {buf} exists and is loaded (shown in a window or hidden). + Checks whether a buffer called {buf} exists and is loaded + (shown in a window or hidden). Returns |TRUE| if so, + |FALSE| otherwise. The {buf} argument is used like with |bufexists()|. Parameters: ~ @@ -712,10 +714,10 @@ bufnr([{buf} [, {create}]]) *bufnr()* (`integer`) bufwinid({buf}) *bufwinid()* - The result is a Number, which is the |window-ID| of the first - window associated with buffer {buf}. For the use of {buf}, - see |bufname()| above. If buffer {buf} doesn't exist or - there is no such window, -1 is returned. Example: >vim + Returns the |window-ID| of the first window associated with + buffer {buf}. For the use of {buf}, see |bufname()| above. + If buffer {buf} doesn't exist or there is no such window, -1 + is returned. Example: >vim echo "A window containing buffer 1 is " .. (bufwinid(1)) < @@ -1099,8 +1101,8 @@ cmdcomplete_info() *cmdcomplete_info()* (`table`) col({expr} [, {winid}]) *col()* - The result is a Number, which is the byte index of the column - position given with {expr}. + Returns the byte index of the column position given with + {expr}. For accepted positions see |getpos()|. When {expr} is "$", it means the end of the cursor line, so the result is the number of bytes in the cursor line plus one. @@ -1947,8 +1949,8 @@ exepath({expr}) *exepath()* (`string`) exists({expr}) *exists()* - The result is a Number, which is |TRUE| if {expr} is - defined, zero otherwise. + Checks whether the expression {expr} is defined. + Returns |TRUE| if {expr} is defined, zero otherwise. For checking for a supported feature use |has()|. For checking if a file exists use |filereadable()|. @@ -2320,12 +2322,12 @@ filecopy({from}, {to}) *filecopy()* (`0|1`) filereadable({file}) *filereadable()* - The result is a Number, which is |TRUE| when a file with the - name {file} exists, and can be read. If {file} doesn't exist, - or is a directory, the result is |FALSE|. {file} is any - expression, which is used as a String. - If you don't care about the file being readable you can use - |glob()|. + Returns |TRUE| if {file} exists, can be read, and is not + a directory, else |FALSE|. + + {file} is any expression, which is used as a String. If you + don't care about the file being readable you can use |glob()|. + {file} is used as-is, you may want to expand wildcards first: >vim echo filereadable('~/.vimrc') < > @@ -2343,9 +2345,9 @@ filereadable({file}) *filereadable()* (`0|1`) filewritable({file}) *filewritable()* - The result is a Number, which is 1 when a file with the - name {file} exists, and can be written. If {file} doesn't - exist, or is not writable, the result is 0. If {file} is a + Checks whether a file with the name {file} exists and can + be written. Returns 1 if so. If {file} doesn't exist, or + is not writable, the result is 0. If {file} is a directory, and we can write to it, the result is 2. Parameters: ~ @@ -2611,9 +2613,9 @@ fnamemodify({fname}, {mods}) *fnamemodify()* (`string`) foldclosed({lnum}) *foldclosed()* - The result is a Number. If the line {lnum} is in a closed - fold, the result is the number of the first line in that fold. - If the line {lnum} is not in a closed fold, -1 is returned. + Returns the first line number of the closed fold containing + line {lnum}. If the line {lnum} is not in a closed fold, + -1 is returned. {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. @@ -2624,9 +2626,9 @@ foldclosed({lnum}) *foldclosed()* (`integer`) foldclosedend({lnum}) *foldclosedend()* - The result is a Number. If the line {lnum} is in a closed - fold, the result is the number of the last line in that fold. - If the line {lnum} is not in a closed fold, -1 is returned. + Returns the last line number of the closed fold containing + line {lnum}. If the line {lnum} is not in a closed fold, + -1 is returned. {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. @@ -2637,16 +2639,17 @@ foldclosedend({lnum}) *foldclosedend()* (`integer`) foldlevel({lnum}) *foldlevel()* - The result is a Number, which is the foldlevel of line {lnum} - in the current buffer. For nested folds the deepest level is - returned. If there is no fold at line {lnum}, zero is - returned. It doesn't matter if the folds are open or closed. - When used while updating folds (from 'foldexpr') -1 is - returned for lines where folds are still to be updated and the - foldlevel is unknown. As a special case the level of the - previous line is usually available. - {lnum} is used like with |getline()|. Thus "." is the current - line, "'m" mark m, etc. + Returns the fold nesting level of line {lnum} in the current + buffer. {lnum} is used like with |getline()| ("." is the + current line, "'m" mark m, etc). + + For nested folds the deepest level is returned. If there is + no fold at line {lnum}, zero is returned. It doesn't matter + if the folds are open or closed. When used while updating + folds (from 'foldexpr') -1 is returned for lines where folds + are still to be updated and the foldlevel is unknown. As + a special case the level of the previous line is usually + available. Parameters: ~ • {lnum} (`integer|string`) @@ -3238,8 +3241,8 @@ getchar([{expr} [, {opts}]]) *getchar()* (`integer|string`) getcharmod() *getcharmod()* - The result is a Number which is the state of the modifiers for - the last obtained character with |getchar()| or in another way. + Returns the state of the keyboard modifiers for the last + character obtained with |getchar()| or in another way. These values are added together: 2 shift 4 control @@ -3613,10 +3616,9 @@ getfontname([{name}]) *getfontname()* (`string`) getfperm({fname}) *getfperm()* - The result is a String, which is the read, write, and execute - permissions of the given file {fname}. - If {fname} does not exist or its directory cannot be read, an - empty string is returned. + Returns the file permissions of the given file {fname} as a + String. If {fname} does not exist or its directory cannot be + read, an empty string is returned. The result is of the form "rwxrwxrwx", where each group of "rwx" flags represent, in turn, the permissions of the owner of the file, the group the file belongs to, and other users. @@ -3636,8 +3638,7 @@ getfperm({fname}) *getfperm()* (`string`) getfsize({fname}) *getfsize()* - The result is a Number, which is the size in bytes of the - given file {fname}. + Returns the size in bytes of the given file {fname}. If {fname} is a directory, 0 is returned. If the file {fname} can't be found, -1 is returned. If the size of {fname} is too big to fit in a Number then -2 @@ -3650,9 +3651,9 @@ getfsize({fname}) *getfsize()* (`integer`) getftime({fname}) *getftime()* - The result is a Number, which is the last modification time of - the given file {fname}. The value is measured as seconds - since 1st Jan 1970, and may be passed to |strftime()|. See also + Returns the last modification time of the given file {fname}. + The value is measured as seconds since 1st Jan 1970, and may + be passed to |strftime()|. See also |localtime()| and |strftime()|. If the file {fname} can't be found -1 is returned. @@ -3663,9 +3664,9 @@ getftime({fname}) *getftime()* (`integer`) getftype({fname}) *getftype()* - The result is a String, which is a description of the kind of - file of the given file {fname}. - If {fname} does not exist an empty string is returned. + Returns a description of the type of file {fname} as a + String. If {fname} does not exist an empty string is + returned. Here is a table over different kinds of files and their results: Normal file "file" @@ -4069,8 +4070,8 @@ getqflist([{what}]) *getqflist()* (`any`) getreg([{regname} [, 1 [, {list}]]]) *getreg()* - The result is a String, which is the contents of register - {regname}. Example: >vim + Returns the contents of register {regname} as a String. + Example: >vim let cliptext = getreg('*') < When register {regname} was not set the result is an empty string. @@ -4240,7 +4241,7 @@ getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()* (`[ [integer, integer, integer, integer], [integer, integer, integer, integer] ][]`) getregtype([{regname}]) *getregtype()* - The result is a String, which is type of register {regname}. + Returns the type of register {regname} as a String. The value will be one of: "v" for |charwise| text "V" for |linewise| text @@ -4388,7 +4389,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* (`any`) gettagstack([{winnr}]) *gettagstack()* - The result is a Dict, which is the tag stack of window {winnr}. + Returns the tag stack of window {winnr} as a Dict. {winnr} can be the window number or the |window-ID|. When {winnr} is not specified, the current window is used. When window {winnr} doesn't exist, an empty Dict is returned. @@ -4482,11 +4483,12 @@ getwininfo([{winid}]) *getwininfo()* (`vim.fn.getwininfo.ret.item[]`) getwinpos([{timeout}]) *getwinpos()* - The result is a |List| with two numbers, the result of - |getwinposx()| and |getwinposy()| combined: - [x-pos, y-pos] + Returns the [x, y] screen position of the Nvim GUI window as + a |List| with two numbers (result of |getwinposx()| and + |getwinposy()| combined). + {timeout} can be used to specify how long to wait in msec for - a response from the terminal. When omitted 100 msec is used. + a response. When omitted 100 msec is used. Use a longer time for a remote terminal. When using a value less than 10 and no response is received @@ -4509,19 +4511,17 @@ getwinpos([{timeout}]) *getwinpos()* (`any`) getwinposx() *getwinposx()* - The result is a Number, which is the X coordinate in pixels of - the left hand side of the GUI Vim window. The result will be - -1 if the information is not available. - The value can be used with `:winpos`. + Returns the X coordinate in pixels of the left hand side of + the Nvim GUI window, or -1 if not available. The value can be + used with `:winpos`. Return: ~ (`integer`) getwinposy() *getwinposy()* - The result is a Number, which is the Y coordinate in pixels of - the top of the GUI Vim window. The result will be -1 if the - information is not available. - The value can be used with `:winpos`. + Returns the Y coordinate in pixels of the top of the Nvim GUI + window, or -1 if not available. The value can be used with + `:winpos`. Return: ~ (`integer`) @@ -4729,8 +4729,8 @@ has({feature}) *has()* (`0|1`) has_key({dict}, {key}) *has_key()* - The result is a Number, which is TRUE if |Dictionary| {dict} - has an entry with key {key}. FALSE otherwise. The {key} + Checks whether |Dictionary| {dict} has an entry with key + {key}. Returns TRUE if so, FALSE otherwise. The {key} argument is a string. Parameters: ~ @@ -4741,9 +4741,10 @@ has_key({dict}, {key}) *has_key()* (`0|1`) haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* - The result is a Number, which is 1 when the window has set a - local path via |:lcd| or when {winnr} is -1 and the tabpage - has set a local path via |:tcd|, otherwise 0. + Checks whether the window or tabpage has set a local working + directory. Returns 1 when the window has set a local path + via |:lcd| or when {winnr} is -1 and the tabpage has set a + local path via |:tcd|, otherwise 0. Tabs and windows are identified by their respective numbers, 0 means current tab or window. Missing argument implies 0. @@ -4765,9 +4766,8 @@ haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* (`0|1`) hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* - The result is a Number, which is TRUE if there is a mapping - that contains {what} in somewhere in the rhs (what it is - mapped to) and this mapping exists in one of the modes + Checks whether a mapping exists whose rhs contains {what}. + Returns TRUE if there is such a mapping in one of the modes indicated by {mode}. The arguments {what} and {mode} are strings. When {abbr} is there and it is |TRUE| use abbreviations @@ -4872,9 +4872,9 @@ histdel({history} [, {item}]) *histdel()* (`0|1`) histget({history} [, {index}]) *histget()* - The result is a String, the entry with Number {index} from - {history}. See |hist-names| for the possible values of - {history}, and |:history-indexing| for {index}. If there is + Returns an entry from the specified command-line {history}. + See |hist-names| for the possible values of {history}, and + |:history-indexing| for {index}. If there is no such entry, an empty String is returned. When {index} is omitted, the most recent item from the history is used. @@ -4910,9 +4910,9 @@ histnr({history}) *histnr()* (`integer`) hlID({name}) *hlID()* - The result is a Number, which is the ID of the highlight group - with name {name}. When the highlight group doesn't exist, - zero is returned. + Returns the numeric ID of the highlight group with name + {name}. When the highlight group doesn't exist, zero is + returned. This can be used to retrieve information about the highlight group. For example, to get the background color of the "Comment" group: >vim @@ -4926,11 +4926,10 @@ hlID({name}) *hlID()* (`integer`) hlexists({name}) *hlexists()* - The result is a Number, which is TRUE if a highlight group - called {name} exists. This is when the group has been - defined in some way. Not necessarily when highlighting has - been defined for it, it may also have been used for a syntax - item. + Checks whether a highlight group called {name} exists. + Returns TRUE if the group has been defined in some way. Not + necessarily when highlighting has been defined for it, it may + also have been used for a syntax item. Parameters: ~ • {name} (`string`) @@ -4939,16 +4938,16 @@ hlexists({name}) *hlexists()* (`0|1`) hostname() *hostname()* - The result is a String, which is the name of the machine on - which Vim is currently running. Machine names greater than + Returns the hostname of the machine on which the Nvim server + (not the UI client) is currently running. Names greater than 256 characters long are truncated. Return: ~ (`string`) iconv({string}, {from}, {to}) *iconv()* - The result is a String, which is the text {string} converted - from encoding {from} to encoding {to}. + Converts the encoding of {string} from {from} to {to}. + Returns the converted String. When the conversion completely fails an empty string is returned. When some characters could not be converted they are replaced with "?". @@ -4990,9 +4989,9 @@ id({expr}) *id()* (`string`) indent({lnum}) *indent()* - The result is a Number, which is indent of line {lnum} in the - current buffer. The indent is counted in spaces, the value - of 'tabstop' is relevant. {lnum} is used just like in + Returns the indent of line {lnum} in the current buffer. + The indent is counted in spaces, the value of 'tabstop' is + relevant. {lnum} is used just like in |getline()|. When {lnum} is invalid -1 is returned. @@ -5099,10 +5098,10 @@ input({prompt} [, {text} [, {completion}]]) *input()* (`string`) input({opts}) - The result is a String, which is whatever the user typed on - the command-line. The {prompt} argument is either a prompt - string, or a blank string (for no prompt). A '\n' can be used - in the prompt to start a new line. + Prompts the user to enter text on the command-line, and + returns the text as a String. The {prompt} argument is either + a prompt string, or a blank string (for no prompt). A '\n' + can be used in the prompt to start a new line. In the second form it accepts a single dictionary with the following keys, any of which may be omitted: @@ -5216,9 +5215,9 @@ input({opts}) (`string`) inputlist({textlist}) *inputlist()* - {textlist} must be a |List| of strings. This |List| is - displayed, one string per line. The user will be prompted to - enter a number, which is returned. + Displays a list of strings and prompts the user to select + one by entering a number. {textlist} must be a |List| of + strings. Returns the number the user entered. The user can also select an item by clicking on it with the mouse, if the mouse is enabled in the command line ('mouse' is "a" or includes "c"). For the first string 0 is returned. @@ -5333,8 +5332,8 @@ invert({expr}) *invert()* (`integer`) isabsolutepath({path}) *isabsolutepath()* - The result is a Number, which is |TRUE| when {path} is an - absolute path. + Checks whether {path} is an absolute path. Returns |TRUE| + if so, |FALSE| otherwise. On Unix, a path is considered absolute when it starts with '/'. On MS-Windows, it is considered absolute when it starts with @@ -5355,10 +5354,9 @@ isabsolutepath({path}) *isabsolutepath()* (`0|1`) isdirectory({directory}) *isdirectory()* - The result is a Number, which is |TRUE| when a directory - with the name {directory} exists. If {directory} doesn't - exist, or isn't a directory, the result is |FALSE|. {directory} - is any expression, which is used as a String. + Returns |TRUE| if {directory} exists, or |FALSE| if it doesn't + exist or isn't a directory. {directory} is any expression, + which is used as a String. Parameters: ~ • {directory} (`string`) @@ -5381,8 +5379,8 @@ isinf({expr}) *isinf()* (`1|0|-1`) islocked({expr}) *islocked()* *E786* - The result is a Number, which is |TRUE| when {expr} is the - name of a locked variable. + Returns |TRUE| if {expr} is the name of a locked variable, + else |FALSE|. The string argument {expr} must be the name of a variable, |List| item or |Dictionary| entry, not the variable itself! Example: >vim @@ -5684,7 +5682,7 @@ keytrans({string}) *keytrans()* (`string`) len({expr}) *len()* *E701* - The result is a Number, which is the length of the argument. + Returns the length of the argument. When {expr} is a String or a Number the length in bytes is used, as with |strlen()|. When {expr} is a |List| the number of items in the |List| is @@ -8220,11 +8218,11 @@ screenattr({row}, {col}) *screenattr()* (`integer`) screenchar({row}, {col}) *screenchar()* - The result is a Number, which is the character at position - [row, col] on the screen. This works for every possible - screen position, also status lines, window separators and the - command line. The top left position is row one, column one - The character excludes composing characters. For double-byte + Returns the character at screen position [row, col] as a + Number. This works for every possible screen position, also + status lines, window separators and the command line. The + top left position is row one, column one. The character + excludes composing characters. For double-byte encodings it may only be the first byte. This is mainly to be used for testing. Returns -1 when row or col is out of range. @@ -8237,9 +8235,10 @@ screenchar({row}, {col}) *screenchar()* (`integer`) screenchars({row}, {col}) *screenchars()* - The result is a |List| of Numbers. The first number is the same - as what |screenchar()| returns. Further numbers are - composing characters on top of the base character. + Returns the character and any composing characters at screen + position [row, col] as a |List| of Numbers. The first number + is the same as what |screenchar()| returns; further numbers + are composing characters on top of the base character. This is mainly to be used for testing. Returns an empty List when row or col is out of range. @@ -8251,8 +8250,8 @@ screenchars({row}, {col}) *screenchars()* (`integer[]`) screencol() *screencol()* - The result is a Number, which is the current screen column of - the cursor. The leftmost column has number 1. + Returns the current screen column of the cursor. The + leftmost column has number 1. This function is mainly used for testing. Note: Always returns the current screen column, thus if used @@ -8269,9 +8268,9 @@ screencol() *screencol()* (`integer`) screenpos({winid}, {lnum}, {col}) *screenpos()* - The result is a Dict with the screen position of the text - character in window {winid} at buffer line {lnum} and column - {col}. {col} is a one-based byte index. + Returns the screen position of the text character in window + {winid} at buffer line {lnum} and column {col} as a Dict. + {col} is a one-based byte index. The Dict has these members: row screen row col first screen column @@ -8301,8 +8300,8 @@ screenpos({winid}, {lnum}, {col}) *screenpos()* (`{ col: integer, curscol: integer, endcol: integer, row: integer }`) screenrow() *screenrow()* - The result is a Number, which is the current screen row of the - cursor. The top line has number one. + Returns the current screen row of the cursor. The top line + has number one. This function is mainly used for testing. Alternatively you can use |winline()|. @@ -8312,10 +8311,9 @@ screenrow() *screenrow()* (`integer`) screenstring({row}, {col}) *screenstring()* - The result is a String that contains the base character and - any composing characters at position [row, col] on the screen. - This is like |screenchars()| but returning a String with the - characters. + Returns the base character and any composing characters at + screen position [row, col] as a String. This is like + |screenchars()| but returning a String with the characters. This is mainly to be used for testing. Returns an empty String when row or col is out of range. @@ -10478,13 +10476,12 @@ str2nr({string} [, {base}]) *str2nr()* (`any`) strcharlen({string}) *strcharlen()* - The result is a Number, which is the number of characters - in String {string}. Composing characters are ignored. + Returns the number of characters in String {string}, ignoring + composing characters. Returns 0 on error or empty {string}. + |strchars()| can count the number of characters, counting composing characters separately. - Returns 0 if {string} is empty or on error. - Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. Parameters: ~ @@ -10518,8 +10515,7 @@ strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* (`string`) strchars({string} [, {skipcc}]) *strchars()* - The result is a Number, which is the number of characters - in String {string}. + Returns the number of characters in String {string}. When {skipcc} is omitted or zero, composing characters are counted separately. When {skipcc} set to 1, composing characters are ignored. @@ -10554,18 +10550,20 @@ strchars({string} [, {skipcc}]) *strchars()* (`integer`) strdisplaywidth({string} [, {col}]) *strdisplaywidth()* - The result is a Number, which is the number of display cells - String {string} occupies on the screen when it starts at {col} - (first column is zero). When {col} is omitted zero is used. - Otherwise it is the screen column where to start. This - matters for Tab characters. + Returns the number of display cells String {string} occupies + on the screen when it starts at {col} (first column is zero). + Returns zero on error. + + When {col} is omitted zero is used. Otherwise it is the screen + column where to start. This matters for Tab characters. The option settings of the current window are used. This matters for anything that's displayed differently, such as 'tabstop' and 'display'. + When {string} contains characters with East Asian Width Class Ambiguous, this function's return value depends on 'ambiwidth'. - Returns zero on error. + Also see |strlen()|, |strwidth()| and |strchars()|. Parameters: ~ @@ -10576,10 +10574,9 @@ strdisplaywidth({string} [, {col}]) *strdisplaywidth()* (`integer`) strftime({format} [, {time}]) *strftime()* - The result is a String, which is a formatted date and time, as - specified by the {format} string. The given {time} is used, - or the current time if no time is given. The accepted - {format} depends on your system, thus this is not portable! + Formats a date and time String specified by {format}. The + given {time} is used, or the current time if no time is given. + The {format} depends on your system, this is not portable! See the manual page of the C function strftime() for the format. The maximum length of the result is 80 characters. See also |localtime()|, |getftime()| and |strptime()|. @@ -10617,8 +10614,8 @@ strgetchar({str}, {index}) *strgetchar()* (`integer`) stridx({haystack}, {needle} [, {start}]) *stridx()* - The result is a Number, which gives the byte index in - {haystack} of the first occurrence of the String {needle}. + Returns the byte index of the first occurrence of {needle} + in {haystack}. If {start} is specified, the search starts at index {start}. This can be used to find a second match: >vim let colon1 = stridx(line, ":") @@ -10644,9 +10641,10 @@ stridx({haystack}, {needle} [, {start}]) *stridx()* (`integer`) string({expr}) *string()* - Return {expr} converted to a String. If {expr} is a Number, - Float, String, Blob or a composition of them, then the result - can be parsed back with |eval()|. + Converts {expr} to a String. If {expr} is a Number, Float, + String, Blob or a composition of them, the result can be + parsed back with |eval()|. + {expr} type result ~ String 'string' Number 123 @@ -10656,14 +10654,16 @@ string({expr}) *string()* Blob 0z00112233.44556677.8899 List [item, item] Dictionary `{key: value, key: value}` - Note that in String values the ' character is doubled. + + Note: in String values the ' character is doubled. Also see |strtrans()|. - Note 2: Output format is mostly compatible with YAML, except - for infinite and NaN floating-point values representations - which use |str2float()|. Strings are also dumped literally, - only single quote is escaped, which does not allow using YAML - for parsing back binary strings. |eval()| should always work - for strings and floats though, and this is the only official + + Note: Output format is mostly compatible with YAML, except for + infinite and NaN floating-point values representations which + use |str2float()|. Strings are also dumped literally, only + single quote is escaped, which does not allow using YAML for + parsing back binary strings. |eval()| should always work for + strings and floats though, and this is the only official method. Use |msgpackdump()| or |json_encode()| if you need to share data with other applications. @@ -10674,8 +10674,7 @@ string({expr}) *string()* (`string`) strlen({string}) *strlen()* - The result is a Number, which is the length of the String - {string} in bytes. + Returns the length of String {string} in bytes. If the argument is a Number it is first converted to a String. For other types an error is given and zero is returned. If you want to count the number of multibyte characters use @@ -10689,12 +10688,14 @@ strlen({string}) *strlen()* (`integer`) strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* - The result is a String, which is part of {src}, starting from - byte {start}, with the byte length {len}. + Gets a substring from {src}, starting from byte {start}, with + byte length {len}. Returns empty string on error. + When {chars} is present and TRUE then {len} is the number of characters positions (composing characters are not counted separately, thus "1" means one base character and any following composing characters). + To count {start} as characters instead of bytes use |strcharpart()|. @@ -10711,7 +10712,6 @@ strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* example, to get the character under the cursor: >vim strpart(getline("."), col(".") - 1, 1, v:true) < - Returns an empty string on error. Parameters: ~ • {src} (`string`) @@ -10723,14 +10723,12 @@ strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* (`string`) strptime({format}, {timestring}) *strptime()* - The result is a Number, which is a unix timestamp representing - the date and time in {timestring}, which is expected to match - the format specified in {format}. + Parses a date/time string and returns a unix timestamp. + {timestring} must match the format specified in {format}. - The accepted {format} depends on your system, thus this is not - portable! See the manual page of the C function strptime() - for the format. Especially avoid "%c". The value of $TZ also - matters. + The {format} depends on your system, this is not portable! + See the strptime() manpage for the format. Especially avoid + "%c". The value of $TZ also matters. If the {timestring} cannot be parsed with {format} zero is returned. If you do not know the format of {timestring} you @@ -10754,8 +10752,8 @@ strptime({format}, {timestring}) *strptime()* (`integer`) strridx({haystack}, {needle} [, {start}]) *strridx()* - The result is a Number, which gives the byte index in - {haystack} of the last occurrence of the String {needle}. + Returns the byte index of the last occurrence of {needle} + in {haystack}. When {start} is specified, matches beyond this index are ignored. This can be used to find a match before a previous match: >vim @@ -10780,9 +10778,9 @@ strridx({haystack}, {needle} [, {start}]) *strridx()* (`integer`) strtrans({string}) *strtrans()* - The result is a String, which is {string} with all unprintable - characters translated into printable characters 'isprint'. - Like they are shown in a window. Example: >vim + Translates all unprintable characters in {string} into + printable characters 'isprint', like they are shown in a + window. Example: >vim echo strtrans(@a) < This displays a newline in register a as "^@" instead of starting a new line. @@ -10796,8 +10794,8 @@ strtrans({string}) *strtrans()* (`string`) strutf16len({string} [, {countcc}]) *strutf16len()* - The result is a Number, which is the number of UTF-16 code - units in String {string} (after converting it to UTF-16). + Returns the number of UTF-16 code units in String {string} + (after converting it to UTF-16). When {countcc} is TRUE, composing characters are counted separately. @@ -10823,9 +10821,9 @@ strutf16len({string} [, {countcc}]) *strutf16len()* (`integer`) strwidth({string}) *strwidth()* - The result is a Number, which is the number of display cells - String {string} occupies. A Tab character is counted as one - cell, alternatively use |strdisplaywidth()|. + Returns the number of display cells String {string} occupies. + A Tab character is counted as one cell, alternatively use + |strdisplaywidth()|. When {string} contains characters with East Asian Width Class Ambiguous, this function's return value depends on 'ambiwidth'. @@ -10874,8 +10872,8 @@ submatch({nr} [, {list}]) *submatch()* *E93 (`string`) substitute({string}, {pat}, {sub}, {flags}) *substitute()* - The result is a String, which is a copy of {string}, in which - the first match of {pat} is replaced with {sub}. + Performs string substitution. Returns a copy of {string} + in which the first match of {pat} is replaced with {sub}. When {flags} is "g", all matches of {pat} in {string} are replaced. Otherwise {flags} should be "". @@ -10941,8 +10939,8 @@ swapfilelist() *swapfilelist()* (`string[]`) swapinfo({fname}) *swapinfo()* - The result is a dictionary, which holds information about the - swapfile {fname}. The available fields are: + Returns information about the swapfile {fname} as a + dictionary. The available fields are: version Vim version user user name host host name @@ -10978,10 +10976,9 @@ swapname({buf}) *swapname()* (`string`) synID({lnum}, {col}, {trans}) *synID()* - The result is a Number, which is the syntax ID at the position - {lnum} and {col} in the current window. - The syntax ID can be used with |synIDattr()| and - |synIDtrans()| to obtain syntax information about text. + Returns the syntax ID at position {lnum} and {col} in the + current window. The syntax ID can be used with |synIDattr()| + and |synIDtrans()| to obtain syntax information about text. {col} is 1 for the leftmost column, {lnum} is 1 for the first line. 'synmaxcol' applies, in a longer line zero is returned. @@ -11012,9 +11009,9 @@ synID({lnum}, {col}, {trans}) *synID()* (`integer`) synIDattr({synID}, {what} [, {mode}]) *synIDattr()* - The result is a String, which is the {what} attribute of - syntax ID {synID}. This can be used to obtain information - about a syntax item. + Returns the {what} attribute of syntax ID {synID} as a + String. This can be used to obtain information about a + syntax item. {mode} can be "gui" or "cterm", to get the attributes for that mode. When {mode} is omitted, or an invalid value is used, the attributes for the currently active highlighting are @@ -11070,9 +11067,9 @@ synIDattr({synID}, {what} [, {mode}]) *synIDattr()* (`string`) synIDtrans({synID}) *synIDtrans()* - The result is a Number, which is the translated syntax ID of - {synID}. This is the syntax group ID of what is being used to - highlight the character. Highlight links given with + Returns the translated syntax ID of {synID}, following + highlight links. This is the syntax group ID of what is + being used to highlight the character. Highlight links given with ":highlight link" are followed. Returns zero on error. @@ -11084,10 +11081,11 @@ synIDtrans({synID}) *synIDtrans()* (`integer`) synconcealed({lnum}, {col}) *synconcealed()* - The result is a |List| with three items: - 1. The first item in the list is 0 if the character at the - position {lnum} and {col} is not part of a concealable - region, 1 if it is. {lnum} is used like with |getline()|. + Returns conceal information for the character at position + {lnum} and {col} as a |List| with three items: + 1. The first item in the list is 0 if the character is not + part of a concealable region, 1 if it is. {lnum} is used + like with |getline()|. 2. The second item in the list is a string. If the first item is 1, the second item contains the text which will be displayed in place of the concealed text, depending on the @@ -11224,8 +11222,8 @@ systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* (`string[]`) tabpagebuflist([{arg}]) *tabpagebuflist()* - The result is a |List|, where each item is the number of the - buffer associated with each window in the current tab page. + Returns a |List| of buffer numbers, one for each window in + the specified tab page. {arg} specifies the number of the tab page to be used. When omitted the current tab page is used. When {arg} is invalid the number zero is returned. @@ -11243,8 +11241,8 @@ tabpagebuflist([{arg}]) *tabpagebuflist()* (`any`) tabpagenr([{arg}]) *tabpagenr()* - The result is a Number, which is the number of the current - tab page. The first tab page has number 1. + Returns the number of the current tab page. The first tab + page has number 1. The optional argument {arg} supports the following values: $ the number of the last tab page (the tab page @@ -11492,9 +11490,8 @@ timer_stopall() *timer_stopall()* (`any`) tolower({expr}) *tolower()* - The result is a copy of the String given, with all uppercase - characters turned into lowercase (just like applying |gu| to - the string). Returns an empty string on error. + Converts a String to lowercase (like applying |gu|). + Returns empty string on error. Parameters: ~ • {expr} (`string`) @@ -11503,9 +11500,8 @@ tolower({expr}) *tolower()* (`string`) toupper({expr}) *toupper()* - The result is a copy of the String given, with all lowercase - characters turned into uppercase (just like applying |gU| to - the string). Returns an empty string on error. + Converts a String to uppercase (like applying |gU|). + Returns empty string on error. Parameters: ~ • {expr} (`string`) @@ -11514,11 +11510,9 @@ toupper({expr}) *toupper()* (`string`) tr({src}, {fromstr}, {tostr}) *tr()* - The result is a copy of the {src} string with all characters - which appear in {fromstr} replaced by the character in that - position in the {tostr} string. Thus the first character in - {fromstr} is translated into the first character in {tostr} - and so on. Exactly like the unix "tr" command. + Translates characters in {src}, replacing each character that + appears in {fromstr} with the corresponding character in + {tostr}. Exactly like the unix "tr" command. This code also deals with multibyte characters properly. Returns an empty string on error. @@ -11593,7 +11587,7 @@ trunc({expr}) *trunc()* (`integer`) type({expr}) *type()* - The result is a Number representing the type of {expr}. + Returns the type of {expr} as a Number. Instead of using the number directly, it is better to use the v:t_ variable that has the value: Number: 0 |v:t_number| @@ -11764,10 +11758,10 @@ values({dict}) *values()* (`any`) virtcol({expr} [, {list} [, {winid}]]) *virtcol()* - The result is a Number, which is the screen column of the file - position given with {expr}. That is, the total number of - screen cells occupied by the part of the line until the end of - the character at that position. When there is a at the + Returns the virtual (screen) column of the file position + given with {expr}. That is, the total number of screen cells + occupied by the part of the line until the end of the + character at that position. When there is a at the position, the returned Number will be the column at the end of the . For example, for a in column 1, with 'ts' set to 8, it returns 8. |conceal| is ignored. @@ -11820,9 +11814,9 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()* (`integer|[integer, integer]`) virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* - The result is a Number, which is the byte index of the - character in window {winid} at buffer line {lnum} and virtual - column {col}. + Converts a virtual column to a byte index. Returns the byte + index of the character in window {winid} at buffer line + {lnum} and virtual column {col}. If buffer line {lnum} is an empty line, 0 is returned. @@ -11850,9 +11844,9 @@ virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* (`integer`) visualmode([{expr}]) *visualmode()* - The result is a String, which describes the last Visual mode - used in the current buffer. Initially it returns an empty - string, but once Visual mode has been used, it returns "v", + Returns a String describing the last Visual mode used in the + current buffer. Initially it returns an empty string, but + once Visual mode has been used, it returns "v", "V", or "" (a single CTRL-V character) for character-wise, line-wise, or block-wise Visual mode respectively. @@ -12124,9 +12118,8 @@ win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* (`any`) winbufnr({nr}) *winbufnr()* - The result is a Number, which is the number of the buffer - associated with window {nr}. {nr} can be the window number or - the |window-ID|. + Returns the buffer number associated with window {nr}. + {nr} can be the window number or the |window-ID|. When {nr} is zero, the number of the buffer in the current window is returned. When window {nr} doesn't exist, -1 is returned. @@ -12141,18 +12134,19 @@ winbufnr({nr}) *winbufnr()* (`integer`) wincol() *wincol()* - The result is a Number, which is the virtual column of the - cursor in the window. This is counting screen cells from the - left side of the window. The leftmost column is one. + Returns the virtual column of the cursor in the window. + This is counting screen cells from the left side of the + window. The leftmost column is one. Return: ~ (`integer`) windowsversion() *windowsversion()* - The result is a String. For MS-Windows it indicates the OS - version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", - Windows XP is "5.1". For non-MS-Windows systems the result is - an empty string. + Returns the Windows OS version as a String. E.g, Windows 10 + is "10.0", Windows 8 is "6.2", Windows XP is "5.1". For + non-MS-Windows systems the result is an empty string. + + See also Lua |uv.os_uname()|. Return: ~ (`string`) @@ -12174,8 +12168,7 @@ winheight({nr}) *winheight()* (`integer`) winlayout([{tabnr}]) *winlayout()* - The result is a nested List containing the layout of windows - in a tabpage. + Returns the layout of windows in a tabpage as a nested List. Without {tabnr} use the current tabpage, otherwise the tabpage with number {tabnr}. If the tabpage {tabnr} is not found, @@ -12217,9 +12210,9 @@ winlayout([{tabnr}]) *winlayout()* (`vim.fn.winlayout.ret`) winline() *winline()* - The result is a Number, which is the screen line of the cursor - in the window. This is counting screen lines from the top of - the window. The first line is one. + Returns the screen line of the cursor in the window. This is + counting screen lines from the top of the window. The first + line is one. If the cursor was moved the view on the file will be updated first, this may cause a scroll. @@ -12227,10 +12220,9 @@ winline() *winline()* (`integer`) winnr([{arg}]) *winnr()* - The result is a Number, which is the number of the current - window. The top window has number 1. - Returns zero for a hidden or non |focusable| window, unless - it is the current window. + Returns the number of the current window. The top window has + number 1. Returns zero for a hidden or non |focusable| + window, unless it is the current window. The optional argument {arg} supports the following values: $ the number of the last window (the window @@ -12356,9 +12348,8 @@ winwidth({nr}) *winwidth()* (`integer`) wordcount() *wordcount()* - The result is a dictionary of byte/chars/word statistics for - the current buffer. This is the same info as provided by - |g_CTRL-G| + Returns a dictionary of byte/chars/word statistics for the + current buffer. This is the same info provided by |g_CTRL-G|. The return value includes: bytes Number of bytes in the buffer chars Number of chars in the buffer diff --git a/runtime/filetype.lua b/runtime/filetype.lua index e471faf75b..e5d12ade7d 100644 --- a/runtime/filetype.lua +++ b/runtime/filetype.lua @@ -7,24 +7,24 @@ vim.api.nvim_create_augroup('filetypedetect', { clear = false }) vim.api.nvim_create_autocmd({ 'BufRead', 'BufNewFile', 'StdinReadPost' }, { group = 'filetypedetect', - callback = function(args) - if not vim.api.nvim_buf_is_valid(args.buf) then + callback = function(ev) + if not vim.api.nvim_buf_is_valid(ev.buf) then return end local ft, on_detect, is_fallback = vim.filetype.match({ -- The unexpanded file name is needed here. #27914 -- However, bufname() can't be used, as it doesn't work with :doautocmd. #31306 - filename = args.file, - buf = args.buf, + filename = ev.file, + buf = ev.buf, }) if ft then -- on_detect is called before setting the filetype so that it can set any buffer local -- variables that may be used the filetype's ftplugin if on_detect then - on_detect(args.buf) + on_detect(ev.buf) end - vim._with({ buf = args.buf }, function() + vim._with({ buf = ev.buf }, function() vim.api.nvim_cmd({ cmd = 'setf', args = (is_fallback and { 'FALLBACK', ft } or { ft }), diff --git a/runtime/lua/tohtml.lua b/runtime/lua/tohtml.lua index 61ea7346ad..a709d4de63 100644 --- a/runtime/lua/tohtml.lua +++ b/runtime/lua/tohtml.lua @@ -203,10 +203,10 @@ local function try_query_terminal_color(color) local hex = nil local au = vim.api.nvim_create_autocmd('TermResponse', { once = true, - callback = function(args) + callback = function(ev) hex = '#' .. table.concat({ - args.data.sequence:match('\027%]%d+;%d*;?rgb:(%w%w)%w%w/(%w%w)%w%w/(%w%w)%w%w'), + ev.data.sequence:match('\027%]%d+;%d*;?rgb:(%w%w)%w%w/(%w%w)%w%w/(%w%w)%w%w'), }) end, }) diff --git a/runtime/lua/vim/_core/defaults.lua b/runtime/lua/vim/_core/defaults.lua index 710e3e1948..f6b4f18e61 100644 --- a/runtime/lua/vim/_core/defaults.lua +++ b/runtime/lua/vim/_core/defaults.lua @@ -566,14 +566,14 @@ do group = nvim_terminal_augroup, nested = true, desc = 'Automatically close terminal buffers when started with no arguments and exiting without an error', - callback = function(args) + callback = function(ev) if vim.v.event.status ~= 0 then return end - local info = vim.api.nvim_get_chan_info(vim.bo[args.buf].channel) + local info = vim.api.nvim_get_chan_info(vim.bo[ev.buf].channel) local argv = info.argv or {} if table.concat(argv, ' ') == vim.o.shell then - vim.api.nvim_buf_delete(args.buf, { force = true }) + vim.api.nvim_buf_delete(ev.buf, { force = true }) end end, }) @@ -581,14 +581,14 @@ do vim.api.nvim_create_autocmd('TermRequest', { group = nvim_terminal_augroup, desc = 'Handles OSC foreground/background color requests', - callback = function(args) + callback = function(ev) --- @type integer - local channel = vim.bo[args.buf].channel + local channel = vim.bo[ev.buf].channel if channel == 0 then return end - local fg_request = args.data.sequence == '\027]10;?' - local bg_request = args.data.sequence == '\027]11;?' + local fg_request = ev.data.sequence == '\027]10;?' + local bg_request = ev.data.sequence == '\027]11;?' if fg_request or bg_request then -- WARN: This does not return the actual foreground/background color, -- but rather returns: @@ -606,7 +606,7 @@ do red, green, blue, - args.data.terminator + ev.data.terminator ) vim.api.nvim_chan_send(channel, data) end @@ -617,12 +617,12 @@ do vim.api.nvim_create_autocmd('TermRequest', { group = nvim_terminal_augroup, desc = 'Mark shell prompts indicated by OSC 133 sequences for navigation', - callback = function(args) - if string.match(args.data.sequence, '^\027]133;A') then - local lnum = args.data.cursor[1] ---@type integer + callback = function(ev) + if string.match(ev.data.sequence, '^\027]133;A') then + local lnum = ev.data.cursor[1] ---@type integer if lnum >= 1 then vim.api.nvim_buf_set_extmark( - args.buf, + ev.buf, nvim_terminal_prompt_ns, lnum - 1, 0, @@ -669,11 +669,11 @@ do vim.api.nvim_create_autocmd('TermOpen', { group = nvim_terminal_augroup, desc = 'Default settings for :terminal buffers', - callback = function(args) - vim.bo[args.buf].modifiable = false - vim.bo[args.buf].undolevels = -1 - vim.bo[args.buf].scrollback = vim.o.scrollback < 0 and 10000 or math.max(1, vim.o.scrollback) - vim.bo[args.buf].textwidth = 0 + callback = function(ev) + vim.bo[ev.buf].modifiable = false + vim.bo[ev.buf].undolevels = -1 + vim.bo[ev.buf].scrollback = vim.o.scrollback < 0 and 10000 or math.max(1, vim.o.scrollback) + vim.bo[ev.buf].textwidth = 0 vim.wo[0][0].wrap = false vim.wo[0][0].list = false vim.wo[0][0].number = false @@ -689,11 +689,11 @@ do vim.wo[0][0].winhighlight = winhl .. 'StatusLine:StatusLineTerm,StatusLineNC:StatusLineTermNC' vim.keymap.set({ 'n', 'x', 'o' }, '[[', function() - jump_to_prompt(nvim_terminal_prompt_ns, 0, args.buf, -vim.v.count1) - end, { buffer = args.buf, desc = 'Jump [count] shell prompts backward' }) + jump_to_prompt(nvim_terminal_prompt_ns, 0, ev.buf, -vim.v.count1) + end, { buffer = ev.buf, desc = 'Jump [count] shell prompts backward' }) vim.keymap.set({ 'n', 'x', 'o' }, ']]', function() - jump_to_prompt(nvim_terminal_prompt_ns, 0, args.buf, vim.v.count1) - end, { buffer = args.buf, desc = 'Jump [count] shell prompts forward' }) + jump_to_prompt(nvim_terminal_prompt_ns, 0, ev.buf, vim.v.count1) + end, { buffer = ev.buf, desc = 'Jump [count] shell prompts forward' }) end, }) @@ -850,8 +850,8 @@ do group = group, nested = true, desc = "Update the value of 'background' automatically based on the terminal emulator's background color", - callback = function(args) - local resp = args.data.sequence ---@type string + callback = function(ev) + local resp = ev.data.sequence ---@type string -- DSR response that should come after the OSC 11 response if the -- terminal supports it. @@ -971,8 +971,8 @@ do local id = vim.api.nvim_create_autocmd('TermResponse', { group = group, nested = true, - callback = function(args) - local resp = args.data.sequence ---@type string + callback = function(ev) + local resp = ev.data.sequence ---@type string local decrqss = resp:match('^\027P1%$r([%d;:]+)m$') if decrqss then diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 2ae4fbc7ec..6102ee7fd7 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -4565,11 +4565,13 @@ vim.bo.ma = vim.bo.modifiable --- result of a BufNewFile, BufRead/BufReadPost, BufWritePost, --- FileAppendPost or VimLeave autocommand event. See `gzip-example` for --- an explanation. +--- +--- When 'buftype' is "prompt", 'modified' is not implicitly set when the +--- buffer is changed, but a user or plugin may explicitly set it. +--- --- When 'buftype' is "nowrite" or "nofile", this option may be set, but ---- it is ignored and will not block closing the window. For "prompt" ---- buffers, changes made to the buffer do not make it count as modified, ---- but an explicit ":set modified" is respected and will block closing the ---- window. +--- will be ignored. +--- --- Note that the text may actually be the same, e.g. 'modified' is set --- when using "rA" on an "A". --- diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index d012b68556..a7407f325c 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -486,8 +486,8 @@ function vim.fn.browsedir(title, initdir) end --- @return integer function vim.fn.bufadd(name) end ---- The result is a Number, which is |TRUE| if a buffer called ---- {buf} exists. +--- Checks whether a buffer with the name or number {buf} exists. +--- Returns |TRUE| if the buffer exists, |FALSE| otherwise. --- If the {buf} argument is a number, buffer numbers are used. --- Number zero is the alternate buffer for the current window. --- @@ -532,8 +532,9 @@ function vim.fn.buffer_name(...) end --- @return integer function vim.fn.buffer_number(...) end ---- The result is a Number, which is |TRUE| if a buffer called ---- {buf} exists and is listed (has the 'buflisted' option set). +--- Checks whether a buffer called {buf} exists and is listed +--- (has the 'buflisted' option set). Returns |TRUE| if so, +--- |FALSE| otherwise. --- The {buf} argument is used like with |bufexists()|. --- --- @param buf any @@ -552,8 +553,9 @@ function vim.fn.buflisted(buf) end --- @param buf any function vim.fn.bufload(buf) end ---- The result is a Number, which is |TRUE| if a buffer called ---- {buf} exists and is loaded (shown in a window or hidden). +--- Checks whether a buffer called {buf} exists and is loaded +--- (shown in a window or hidden). Returns |TRUE| if so, +--- |FALSE| otherwise. --- The {buf} argument is used like with |bufexists()|. --- --- @param buf any @@ -616,10 +618,10 @@ function vim.fn.bufname(buf) end --- @return integer function vim.fn.bufnr(buf, create) end ---- The result is a Number, which is the |window-ID| of the first ---- window associated with buffer {buf}. For the use of {buf}, ---- see |bufname()| above. If buffer {buf} doesn't exist or ---- there is no such window, -1 is returned. Example: >vim +--- Returns the |window-ID| of the first window associated with +--- buffer {buf}. For the use of {buf}, see |bufname()| above. +--- If buffer {buf} doesn't exist or there is no such window, -1 +--- is returned. Example: >vim --- --- echo "A window containing buffer 1 is " .. (bufwinid(1)) --- < @@ -955,8 +957,8 @@ function vim.fn.clearmatches(win) end --- @return table function vim.fn.cmdcomplete_info() end ---- The result is a Number, which is the byte index of the column ---- position given with {expr}. +--- Returns the byte index of the column position given with +--- {expr}. --- For accepted positions see |getpos()|. --- When {expr} is "$", it means the end of the cursor line, so --- the result is the number of bytes in the cursor line plus one. @@ -1713,8 +1715,8 @@ function vim.fn.execute(command, silent) end --- @return string function vim.fn.exepath(expr) end ---- The result is a Number, which is |TRUE| if {expr} is ---- defined, zero otherwise. +--- Checks whether the expression {expr} is defined. +--- Returns |TRUE| if {expr} is defined, zero otherwise. --- --- For checking for a supported feature use |has()|. --- For checking if a file exists use |filereadable()|. @@ -2075,12 +2077,12 @@ function vim.fn.file_readable(file) end --- @return 0|1 function vim.fn.filecopy(from, to) end ---- The result is a Number, which is |TRUE| when a file with the ---- name {file} exists, and can be read. If {file} doesn't exist, ---- or is a directory, the result is |FALSE|. {file} is any ---- expression, which is used as a String. ---- If you don't care about the file being readable you can use ---- |glob()|. +--- Returns |TRUE| if {file} exists, can be read, and is not +--- a directory, else |FALSE|. +--- +--- {file} is any expression, which is used as a String. If you +--- don't care about the file being readable you can use |glob()|. +--- --- {file} is used as-is, you may want to expand wildcards first: >vim --- echo filereadable('~/.vimrc') --- < > @@ -2095,9 +2097,9 @@ function vim.fn.filecopy(from, to) end --- @return 0|1 function vim.fn.filereadable(file) end ---- The result is a Number, which is 1 when a file with the ---- name {file} exists, and can be written. If {file} doesn't ---- exist, or is not writable, the result is 0. If {file} is a +--- Checks whether a file with the name {file} exists and can +--- be written. Returns 1 if so. If {file} doesn't exist, or +--- is not writable, the result is 0. If {file} is a --- directory, and we can write to it, the result is 2. --- --- @param file string @@ -2330,9 +2332,9 @@ function vim.fn.fnameescape(string) end --- @return string function vim.fn.fnamemodify(fname, mods) end ---- The result is a Number. If the line {lnum} is in a closed ---- fold, the result is the number of the first line in that fold. ---- If the line {lnum} is not in a closed fold, -1 is returned. +--- Returns the first line number of the closed fold containing +--- line {lnum}. If the line {lnum} is not in a closed fold, +--- -1 is returned. --- {lnum} is used like with |getline()|. Thus "." is the current --- line, "'m" mark m, etc. --- @@ -2340,9 +2342,9 @@ function vim.fn.fnamemodify(fname, mods) end --- @return integer function vim.fn.foldclosed(lnum) end ---- The result is a Number. If the line {lnum} is in a closed ---- fold, the result is the number of the last line in that fold. ---- If the line {lnum} is not in a closed fold, -1 is returned. +--- Returns the last line number of the closed fold containing +--- line {lnum}. If the line {lnum} is not in a closed fold, +--- -1 is returned. --- {lnum} is used like with |getline()|. Thus "." is the current --- line, "'m" mark m, etc. --- @@ -2350,16 +2352,17 @@ function vim.fn.foldclosed(lnum) end --- @return integer function vim.fn.foldclosedend(lnum) end ---- The result is a Number, which is the foldlevel of line {lnum} ---- in the current buffer. For nested folds the deepest level is ---- returned. If there is no fold at line {lnum}, zero is ---- returned. It doesn't matter if the folds are open or closed. ---- When used while updating folds (from 'foldexpr') -1 is ---- returned for lines where folds are still to be updated and the ---- foldlevel is unknown. As a special case the level of the ---- previous line is usually available. ---- {lnum} is used like with |getline()|. Thus "." is the current ---- line, "'m" mark m, etc. +--- Returns the fold nesting level of line {lnum} in the current +--- buffer. {lnum} is used like with |getline()| ("." is the +--- current line, "'m" mark m, etc). +--- +--- For nested folds the deepest level is returned. If there is +--- no fold at line {lnum}, zero is returned. It doesn't matter +--- if the folds are open or closed. When used while updating +--- folds (from 'foldexpr') -1 is returned for lines where folds +--- are still to be updated and the foldlevel is unknown. As +--- a special case the level of the previous line is usually +--- available. --- --- @param lnum integer|string --- @return integer @@ -2901,8 +2904,8 @@ function vim.fn.getchangelist(buf) end --- @return integer|string function vim.fn.getchar(expr, opts) end ---- The result is a Number which is the state of the modifiers for ---- the last obtained character with |getchar()| or in another way. +--- Returns the state of the keyboard modifiers for the last +--- character obtained with |getchar()| or in another way. --- These values are added together: --- 2 shift --- 4 control @@ -3239,10 +3242,9 @@ function vim.fn.getenv(name) end --- @return string function vim.fn.getfontname(name) end ---- The result is a String, which is the read, write, and execute ---- permissions of the given file {fname}. ---- If {fname} does not exist or its directory cannot be read, an ---- empty string is returned. +--- Returns the file permissions of the given file {fname} as a +--- String. If {fname} does not exist or its directory cannot be +--- read, an empty string is returned. --- The result is of the form "rwxrwxrwx", where each group of --- "rwx" flags represent, in turn, the permissions of the owner --- of the file, the group the file belongs to, and other users. @@ -3259,8 +3261,7 @@ function vim.fn.getfontname(name) end --- @return string function vim.fn.getfperm(fname) end ---- The result is a Number, which is the size in bytes of the ---- given file {fname}. +--- Returns the size in bytes of the given file {fname}. --- If {fname} is a directory, 0 is returned. --- If the file {fname} can't be found, -1 is returned. --- If the size of {fname} is too big to fit in a Number then -2 @@ -3270,9 +3271,9 @@ function vim.fn.getfperm(fname) end --- @return integer function vim.fn.getfsize(fname) end ---- The result is a Number, which is the last modification time of ---- the given file {fname}. The value is measured as seconds ---- since 1st Jan 1970, and may be passed to |strftime()|. See also +--- Returns the last modification time of the given file {fname}. +--- The value is measured as seconds since 1st Jan 1970, and may +--- be passed to |strftime()|. See also --- |localtime()| and |strftime()|. --- If the file {fname} can't be found -1 is returned. --- @@ -3280,9 +3281,9 @@ function vim.fn.getfsize(fname) end --- @return integer function vim.fn.getftime(fname) end ---- The result is a String, which is a description of the kind of ---- file of the given file {fname}. ---- If {fname} does not exist an empty string is returned. +--- Returns a description of the type of file {fname} as a +--- String. If {fname} does not exist an empty string is +--- returned. --- Here is a table over different kinds of files and their --- results: --- Normal file "file" @@ -3665,8 +3666,8 @@ function vim.fn.getpos(expr) end --- @return any function vim.fn.getqflist(what) end ---- The result is a String, which is the contents of register ---- {regname}. Example: >vim +--- Returns the contents of register {regname} as a String. +--- Example: >vim --- let cliptext = getreg('*') --- vim @@ -4460,25 +4460,24 @@ function vim.fn.histnr(history) end --- @return integer function vim.fn.hlID(name) end ---- The result is a Number, which is TRUE if a highlight group ---- called {name} exists. This is when the group has been ---- defined in some way. Not necessarily when highlighting has ---- been defined for it, it may also have been used for a syntax ---- item. +--- Checks whether a highlight group called {name} exists. +--- Returns TRUE if the group has been defined in some way. Not +--- necessarily when highlighting has been defined for it, it may +--- also have been used for a syntax item. --- --- @param name string --- @return 0|1 function vim.fn.hlexists(name) end ---- The result is a String, which is the name of the machine on ---- which Vim is currently running. Machine names greater than +--- Returns the hostname of the machine on which the Nvim server +--- (not the UI client) is currently running. Names greater than --- 256 characters long are truncated. --- --- @return string function vim.fn.hostname() end ---- The result is a String, which is the text {string} converted ---- from encoding {from} to encoding {to}. +--- Converts the encoding of {string} from {from} to {to}. +--- Returns the converted String. --- When the conversion completely fails an empty string is --- returned. When some characters could not be converted they --- are replaced with "?". @@ -4514,9 +4513,9 @@ function vim.fn.iconv(string, from, to) end --- @return string function vim.fn.id(expr) end ---- The result is a Number, which is indent of line {lnum} in the ---- current buffer. The indent is counted in spaces, the value ---- of 'tabstop' is relevant. {lnum} is used just like in +--- Returns the indent of line {lnum} in the current buffer. +--- The indent is counted in spaces, the value of 'tabstop' is +--- relevant. {lnum} is used just like in --- |getline()|. --- When {lnum} is invalid -1 is returned. --- @@ -4611,10 +4610,10 @@ function vim.fn.indexof(object, expr, opts) end --- @return string function vim.fn.input(prompt, text, completion) end ---- The result is a String, which is whatever the user typed on ---- the command-line. The {prompt} argument is either a prompt ---- string, or a blank string (for no prompt). A '\n' can be used ---- in the prompt to start a new line. +--- Prompts the user to enter text on the command-line, and +--- returns the text as a String. The {prompt} argument is either +--- a prompt string, or a blank string (for no prompt). A '\n' +--- can be used in the prompt to start a new line. --- --- In the second form it accepts a single dictionary with the --- following keys, any of which may be omitted: @@ -4732,9 +4731,9 @@ function vim.fn.input(opts) end --- @return any function vim.fn.inputdialog(...) end ---- {textlist} must be a |List| of strings. This |List| is ---- displayed, one string per line. The user will be prompted to ---- enter a number, which is returned. +--- Displays a list of strings and prompts the user to select +--- one by entering a number. {textlist} must be a |List| of +--- strings. Returns the number the user entered. --- The user can also select an item by clicking on it with the --- mouse, if the mouse is enabled in the command line ('mouse' is --- "a" or includes "c"). For the first string 0 is returned. @@ -4834,8 +4833,8 @@ function vim.fn.interrupt() end --- @return integer function vim.fn.invert(expr) end ---- The result is a Number, which is |TRUE| when {path} is an ---- absolute path. +--- Checks whether {path} is an absolute path. Returns |TRUE| +--- if so, |FALSE| otherwise. --- On Unix, a path is considered absolute when it starts with --- '/'. --- On MS-Windows, it is considered absolute when it starts with @@ -4853,10 +4852,9 @@ function vim.fn.invert(expr) end --- @return 0|1 function vim.fn.isabsolutepath(path) end ---- The result is a Number, which is |TRUE| when a directory ---- with the name {directory} exists. If {directory} doesn't ---- exist, or isn't a directory, the result is |FALSE|. {directory} ---- is any expression, which is used as a String. +--- Returns |TRUE| if {directory} exists, or |FALSE| if it doesn't +--- exist or isn't a directory. {directory} is any expression, +--- which is used as a String. --- --- @param directory string --- @return 0|1 @@ -4873,8 +4871,8 @@ function vim.fn.isdirectory(directory) end --- @return 1|0|-1 function vim.fn.isinf(expr) end ---- The result is a Number, which is |TRUE| when {expr} is the ---- name of a locked variable. +--- Returns |TRUE| if {expr} is the name of a locked variable, +--- else |FALSE|. --- The string argument {expr} must be the name of a variable, --- |List| item or |Dictionary| entry, not the variable itself! --- Example: >vim @@ -5157,7 +5155,7 @@ function vim.fn.keytrans(string) end --- @return any function vim.fn.last_buffer_nr() end ---- The result is a Number, which is the length of the argument. +--- Returns the length of the argument. --- When {expr} is a String or a Number the length in bytes is --- used, as with |strlen()|. --- When {expr} is a |List| the number of items in the |List| is @@ -7482,11 +7480,11 @@ function vim.fn.rubyeval(expr) end --- @return integer function vim.fn.screenattr(row, col) end ---- The result is a Number, which is the character at position ---- [row, col] on the screen. This works for every possible ---- screen position, also status lines, window separators and the ---- command line. The top left position is row one, column one ---- The character excludes composing characters. For double-byte +--- Returns the character at screen position [row, col] as a +--- Number. This works for every possible screen position, also +--- status lines, window separators and the command line. The +--- top left position is row one, column one. The character +--- excludes composing characters. For double-byte --- encodings it may only be the first byte. --- This is mainly to be used for testing. --- Returns -1 when row or col is out of range. @@ -7496,9 +7494,10 @@ function vim.fn.screenattr(row, col) end --- @return integer function vim.fn.screenchar(row, col) end ---- The result is a |List| of Numbers. The first number is the same ---- as what |screenchar()| returns. Further numbers are ---- composing characters on top of the base character. +--- Returns the character and any composing characters at screen +--- position [row, col] as a |List| of Numbers. The first number +--- is the same as what |screenchar()| returns; further numbers +--- are composing characters on top of the base character. --- This is mainly to be used for testing. --- Returns an empty List when row or col is out of range. --- @@ -7507,8 +7506,8 @@ function vim.fn.screenchar(row, col) end --- @return integer[] function vim.fn.screenchars(row, col) end ---- The result is a Number, which is the current screen column of ---- the cursor. The leftmost column has number 1. +--- Returns the current screen column of the cursor. The +--- leftmost column has number 1. --- This function is mainly used for testing. --- --- Note: Always returns the current screen column, thus if used @@ -7524,9 +7523,9 @@ function vim.fn.screenchars(row, col) end --- @return integer function vim.fn.screencol() end ---- The result is a Dict with the screen position of the text ---- character in window {winid} at buffer line {lnum} and column ---- {col}. {col} is a one-based byte index. +--- Returns the screen position of the text character in window +--- {winid} at buffer line {lnum} and column {col} as a Dict. +--- {col} is a one-based byte index. --- The Dict has these members: --- row screen row --- col first screen column @@ -7553,8 +7552,8 @@ function vim.fn.screencol() end --- @return { col: integer, curscol: integer, endcol: integer, row: integer } function vim.fn.screenpos(winid, lnum, col) end ---- The result is a Number, which is the current screen row of the ---- cursor. The top line has number one. +--- Returns the current screen row of the cursor. The top line +--- has number one. --- This function is mainly used for testing. --- Alternatively you can use |winline()|. --- @@ -7563,10 +7562,9 @@ function vim.fn.screenpos(winid, lnum, col) end --- @return integer function vim.fn.screenrow() end ---- The result is a String that contains the base character and ---- any composing characters at position [row, col] on the screen. ---- This is like |screenchars()| but returning a String with the ---- characters. +--- Returns the base character and any composing characters at +--- screen position [row, col] as a String. This is like +--- |screenchars()| but returning a String with the characters. --- This is mainly to be used for testing. --- Returns an empty String when row or col is out of range. --- @@ -9566,13 +9564,12 @@ function vim.fn.str2list(string, utf8) end --- @return any function vim.fn.str2nr(string, base) end ---- The result is a Number, which is the number of characters ---- in String {string}. Composing characters are ignored. +--- Returns the number of characters in String {string}, ignoring +--- composing characters. Returns 0 on error or empty {string}. +--- --- |strchars()| can count the number of characters, counting --- composing characters separately. --- ---- Returns 0 if {string} is empty or on error. ---- --- Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. --- --- @param string string @@ -9600,8 +9597,7 @@ function vim.fn.strcharlen(string) end --- @return string function vim.fn.strcharpart(src, start, len, skipcc) end ---- The result is a Number, which is the number of characters ---- in String {string}. +--- Returns the number of characters in String {string}. --- When {skipcc} is omitted or zero, composing characters are --- counted separately. --- When {skipcc} set to 1, composing characters are ignored. @@ -9633,18 +9629,20 @@ function vim.fn.strcharpart(src, start, len, skipcc) end --- @return integer function vim.fn.strchars(string, skipcc) end ---- The result is a Number, which is the number of display cells ---- String {string} occupies on the screen when it starts at {col} ---- (first column is zero). When {col} is omitted zero is used. ---- Otherwise it is the screen column where to start. This ---- matters for Tab characters. +--- Returns the number of display cells String {string} occupies +--- on the screen when it starts at {col} (first column is zero). +--- Returns zero on error. +--- +--- When {col} is omitted zero is used. Otherwise it is the screen +--- column where to start. This matters for Tab characters. --- The option settings of the current window are used. This --- matters for anything that's displayed differently, such as --- 'tabstop' and 'display'. +--- --- When {string} contains characters with East Asian Width Class --- Ambiguous, this function's return value depends on --- 'ambiwidth'. ---- Returns zero on error. +--- --- Also see |strlen()|, |strwidth()| and |strchars()|. --- --- @param string string @@ -9652,10 +9650,9 @@ function vim.fn.strchars(string, skipcc) end --- @return integer function vim.fn.strdisplaywidth(string, col) end ---- The result is a String, which is a formatted date and time, as ---- specified by the {format} string. The given {time} is used, ---- or the current time if no time is given. The accepted ---- {format} depends on your system, thus this is not portable! +--- Formats a date and time String specified by {format}. The +--- given {time} is used, or the current time if no time is given. +--- The {format} depends on your system, this is not portable! --- See the manual page of the C function strftime() for the --- format. The maximum length of the result is 80 characters. --- See also |localtime()|, |getftime()| and |strptime()|. @@ -9687,8 +9684,8 @@ function vim.fn.strftime(format, time) end --- @return integer function vim.fn.strgetchar(str, index) end ---- The result is a Number, which gives the byte index in ---- {haystack} of the first occurrence of the String {needle}. +--- Returns the byte index of the first occurrence of {needle} +--- in {haystack}. --- If {start} is specified, the search starts at index {start}. --- This can be used to find a second match: >vim --- let colon1 = stridx(line, ":") @@ -9711,9 +9708,10 @@ function vim.fn.strgetchar(str, index) end --- @return integer function vim.fn.stridx(haystack, needle, start) end ---- Return {expr} converted to a String. If {expr} is a Number, ---- Float, String, Blob or a composition of them, then the result ---- can be parsed back with |eval()|. +--- Converts {expr} to a String. If {expr} is a Number, Float, +--- String, Blob or a composition of them, the result can be +--- parsed back with |eval()|. +--- --- {expr} type result ~ --- String 'string' --- Number 123 @@ -9723,14 +9721,16 @@ function vim.fn.stridx(haystack, needle, start) end --- Blob 0z00112233.44556677.8899 --- List [item, item] --- Dictionary `{key: value, key: value}` ---- Note that in String values the ' character is doubled. +--- +--- Note: in String values the ' character is doubled. --- Also see |strtrans()|. ---- Note 2: Output format is mostly compatible with YAML, except ---- for infinite and NaN floating-point values representations ---- which use |str2float()|. Strings are also dumped literally, ---- only single quote is escaped, which does not allow using YAML ---- for parsing back binary strings. |eval()| should always work ---- for strings and floats though, and this is the only official +--- +--- Note: Output format is mostly compatible with YAML, except for +--- infinite and NaN floating-point values representations which +--- use |str2float()|. Strings are also dumped literally, only +--- single quote is escaped, which does not allow using YAML for +--- parsing back binary strings. |eval()| should always work for +--- strings and floats though, and this is the only official --- method. Use |msgpackdump()| or |json_encode()| if you need to --- share data with other applications. --- @@ -9738,8 +9738,7 @@ function vim.fn.stridx(haystack, needle, start) end --- @return string function vim.fn.string(expr) end ---- The result is a Number, which is the length of the String ---- {string} in bytes. +--- Returns the length of String {string} in bytes. --- If the argument is a Number it is first converted to a String. --- For other types an error is given and zero is returned. --- If you want to count the number of multibyte characters use @@ -9750,12 +9749,14 @@ function vim.fn.string(expr) end --- @return integer function vim.fn.strlen(string) end ---- The result is a String, which is part of {src}, starting from ---- byte {start}, with the byte length {len}. +--- Gets a substring from {src}, starting from byte {start}, with +--- byte length {len}. Returns empty string on error. +--- --- When {chars} is present and TRUE then {len} is the number of --- characters positions (composing characters are not counted --- separately, thus "1" means one base character and any --- following composing characters). +--- --- To count {start} as characters instead of bytes use --- |strcharpart()|. --- @@ -9772,7 +9773,6 @@ function vim.fn.strlen(string) end --- example, to get the character under the cursor: >vim --- strpart(getline("."), col(".") - 1, 1, v:true) --- < ---- Returns an empty string on error. --- --- @param src string --- @param start integer @@ -9781,14 +9781,12 @@ function vim.fn.strlen(string) end --- @return string function vim.fn.strpart(src, start, len, chars) end ---- The result is a Number, which is a unix timestamp representing ---- the date and time in {timestring}, which is expected to match ---- the format specified in {format}. +--- Parses a date/time string and returns a unix timestamp. +--- {timestring} must match the format specified in {format}. --- ---- The accepted {format} depends on your system, thus this is not ---- portable! See the manual page of the C function strptime() ---- for the format. Especially avoid "%c". The value of $TZ also ---- matters. +--- The {format} depends on your system, this is not portable! +--- See the strptime() manpage for the format. Especially avoid +--- "%c". The value of $TZ also matters. --- --- If the {timestring} cannot be parsed with {format} zero is --- returned. If you do not know the format of {timestring} you @@ -9809,8 +9807,8 @@ function vim.fn.strpart(src, start, len, chars) end --- @return integer function vim.fn.strptime(format, timestring) end ---- The result is a Number, which gives the byte index in ---- {haystack} of the last occurrence of the String {needle}. +--- Returns the byte index of the last occurrence of {needle} +--- in {haystack}. --- When {start} is specified, matches beyond this index are --- ignored. This can be used to find a match before a previous --- match: >vim @@ -9832,9 +9830,9 @@ function vim.fn.strptime(format, timestring) end --- @return integer function vim.fn.strridx(haystack, needle, start) end ---- The result is a String, which is {string} with all unprintable ---- characters translated into printable characters 'isprint'. ---- Like they are shown in a window. Example: >vim +--- Translates all unprintable characters in {string} into +--- printable characters 'isprint', like they are shown in a +--- window. Example: >vim --- echo strtrans(\@a) --- at the +--- Returns the virtual (screen) column of the file position +--- given with {expr}. That is, the total number of screen cells +--- occupied by the part of the line until the end of the +--- character at that position. When there is a at the --- position, the returned Number will be the column at the end of --- the . For example, for a in column 1, with 'ts' --- set to 8, it returns 8. |conceal| is ignored. @@ -10764,9 +10758,9 @@ function vim.fn.values(dict) end --- @return integer|[integer, integer] function vim.fn.virtcol(expr, list, winid) end ---- The result is a Number, which is the byte index of the ---- character in window {winid} at buffer line {lnum} and virtual ---- column {col}. +--- Converts a virtual column to a byte index. Returns the byte +--- index of the character in window {winid} at buffer line +--- {lnum} and virtual column {col}. --- --- If buffer line {lnum} is an empty line, 0 is returned. --- @@ -10791,9 +10785,9 @@ function vim.fn.virtcol(expr, list, winid) end --- @return integer function vim.fn.virtcol2col(winid, lnum, col) end ---- The result is a String, which describes the last Visual mode ---- used in the current buffer. Initially it returns an empty ---- string, but once Visual mode has been used, it returns "v", +--- Returns a String describing the last Visual mode used in the +--- current buffer. Initially it returns an empty string, but +--- once Visual mode has been used, it returns "v", --- "V", or "" (a single CTRL-V character) for --- character-wise, line-wise, or block-wise Visual mode --- respectively. @@ -11024,9 +11018,8 @@ function vim.fn.win_screenpos(nr) end --- @return any function vim.fn.win_splitmove(nr, target, options) end ---- The result is a Number, which is the number of the buffer ---- associated with window {nr}. {nr} can be the window number or ---- the |window-ID|. +--- Returns the buffer number associated with window {nr}. +--- {nr} can be the window number or the |window-ID|. --- When {nr} is zero, the number of the buffer in the current --- window is returned. --- When window {nr} doesn't exist, -1 is returned. @@ -11038,17 +11031,18 @@ function vim.fn.win_splitmove(nr, target, options) end --- @return integer function vim.fn.winbufnr(nr) end ---- The result is a Number, which is the virtual column of the ---- cursor in the window. This is counting screen cells from the ---- left side of the window. The leftmost column is one. +--- Returns the virtual column of the cursor in the window. +--- This is counting screen cells from the left side of the +--- window. The leftmost column is one. --- --- @return integer function vim.fn.wincol() end ---- The result is a String. For MS-Windows it indicates the OS ---- version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", ---- Windows XP is "5.1". For non-MS-Windows systems the result is ---- an empty string. +--- Returns the Windows OS version as a String. E.g, Windows 10 +--- is "10.0", Windows 8 is "6.2", Windows XP is "5.1". For +--- non-MS-Windows systems the result is an empty string. +--- +--- See also Lua |uv.os_uname()|. --- --- @return string function vim.fn.windowsversion() end @@ -11066,8 +11060,7 @@ function vim.fn.windowsversion() end --- @return integer function vim.fn.winheight(nr) end ---- The result is a nested List containing the layout of windows ---- in a tabpage. +--- Returns the layout of windows in a tabpage as a nested List. --- --- Without {tabnr} use the current tabpage, otherwise the tabpage --- with number {tabnr}. If the tabpage {tabnr} is not found, @@ -11106,19 +11099,18 @@ function vim.fn.winheight(nr) end --- @return vim.fn.winlayout.ret function vim.fn.winlayout(tabnr) end ---- The result is a Number, which is the screen line of the cursor ---- in the window. This is counting screen lines from the top of ---- the window. The first line is one. +--- Returns the screen line of the cursor in the window. This is +--- counting screen lines from the top of the window. The first +--- line is one. --- If the cursor was moved the view on the file will be updated --- first, this may cause a scroll. --- --- @return integer function vim.fn.winline() end ---- The result is a Number, which is the number of the current ---- window. The top window has number 1. ---- Returns zero for a hidden or non |focusable| window, unless ---- it is the current window. +--- Returns the number of the current window. The top window has +--- number 1. Returns zero for a hidden or non |focusable| +--- window, unless it is the current window. --- --- The optional argument {arg} supports the following values: --- $ the number of the last window (the window @@ -11233,9 +11225,8 @@ function vim.fn.winsaveview() end --- @return integer function vim.fn.winwidth(nr) end ---- The result is a dictionary of byte/chars/word statistics for ---- the current buffer. This is the same info as provided by ---- |g_CTRL-G| +--- Returns a dictionary of byte/chars/word statistics for the +--- current buffer. This is the same info provided by |g_CTRL-G|. --- The return value includes: --- bytes Number of bytes in the buffer --- chars Number of chars in the buffer diff --git a/runtime/lua/vim/health/health.lua b/runtime/lua/vim/health/health.lua index 8f57de4615..42e7bdb067 100644 --- a/runtime/lua/vim/health/health.lua +++ b/runtime/lua/vim/health/health.lua @@ -670,8 +670,8 @@ local function check_sysinfo() vim.api.nvim_create_autocmd('FileType', { pattern = 'checkhealth', once = true, - callback = function(args) - local buf = args.buf + callback = function(ev) + local buf = ev.buf local win = vim.fn.bufwinid(buf) if win == -1 then return diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 5aa473968f..0764c28b44 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -563,8 +563,8 @@ function lsp.enable(name, enable) lsp_enable_autocmd_id = lsp_enable_autocmd_id or api.nvim_create_autocmd('FileType', { group = api.nvim_create_augroup('nvim.lsp.enable', {}), - callback = function(args) - lsp_enable_callback(args.buf) + callback = function(ev) + lsp_enable_callback(ev.buf) end, }) end @@ -1431,8 +1431,8 @@ end --- vim.o.foldexpr = 'v:lua.vim.treesitter.foldexpr()' --- -- Prefer LSP folding if client supports it --- vim.api.nvim_create_autocmd('LspAttach', { ---- callback = function(args) ---- local client = vim.lsp.get_client_by_id(args.data.client_id) +--- callback = function(ev) +--- local client = vim.lsp.get_client_by_id(ev.data.client_id) --- if client:supports_method('textDocument/foldingRange') then --- local win = vim.api.nvim_get_current_win() --- vim.wo[win][0].foldexpr = 'v:lua.vim.lsp.foldexpr()' @@ -1452,9 +1452,9 @@ end --- --- ```lua --- vim.api.nvim_create_autocmd('LspNotify', { ---- callback = function(args) ---- if args.data.method == 'textDocument/didOpen' then ---- vim.lsp.foldclose('imports', vim.fn.bufwinid(args.buf)) +--- callback = function(ev) +--- if ev.data.method == 'textDocument/didOpen' then +--- vim.lsp.foldclose('imports', vim.fn.bufwinid(ev.buf)) --- end --- end, --- }) diff --git a/runtime/lua/vim/lsp/_folding_range.lua b/runtime/lua/vim/lsp/_folding_range.lua index cac6d7ec2a..a3e4a16527 100644 --- a/runtime/lua/vim/lsp/_folding_range.lua +++ b/runtime/lua/vim/lsp/_folding_range.lua @@ -231,14 +231,11 @@ function State:new(bufnr) api.nvim_create_autocmd('LspNotify', { group = self.augroup, buffer = bufnr, - callback = function(args) - local client = assert(vim.lsp.get_client_by_id(args.data.client_id)) + callback = function(ev) + local client = assert(vim.lsp.get_client_by_id(ev.data.client_id)) if client:supports_method('textDocument/foldingRange', bufnr) - and ( - args.data.method == 'textDocument/didChange' - or args.data.method == 'textDocument/didOpen' - ) + and (ev.data.method == 'textDocument/didChange' or ev.data.method == 'textDocument/didOpen') then self:refresh(client) end diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua index a8fc61807c..d70a61d0da 100644 --- a/runtime/lua/vim/lsp/completion.lua +++ b/runtime/lua/vim/lsp/completion.lua @@ -768,7 +768,7 @@ local function on_completechanged(group, bufnr) api.nvim_create_autocmd('CompleteChanged', { group = group, buffer = bufnr, - callback = function(args) + callback = function(ev) local completed_item = vim.v.event.completed_item or {} if (completed_item.info or '') ~= '' then local data = vim.fn.complete_info({ 'selected' }) @@ -780,7 +780,7 @@ local function on_completechanged(group, bufnr) #lsp.get_clients({ id = vim.tbl_get(completed_item, 'user_data', 'nvim', 'lsp', 'client_id'), method = 'completionItem/resolve', - bufnr = args.buf, + bufnr = ev.buf, }) == 0 then return @@ -791,7 +791,7 @@ local function on_completechanged(group, bufnr) local param = vim.tbl_get(completed_item, 'user_data', 'nvim', 'lsp', 'completion_item') if param then Context.resolve_handler = Context.resolve_handler or CompletionResolver.new() - Context.resolve_handler:request(args.buf, param, completed_item.word) + Context.resolve_handler:request(ev.buf, param, completed_item.word) end end, desc = 'Request and display LSP completion item documentation via completionItem/resolve', @@ -1121,8 +1121,8 @@ local function enable_completions(client_id, bufnr, opts) group = group, buffer = bufnr, desc = 'vim.lsp.completion: clean up client on detach', - callback = function(args) - disable_completions(args.data.client_id, args.buf) + callback = function(ev) + disable_completions(ev.data.client_id, ev.buf) end, }) diff --git a/runtime/lua/vim/lsp/diagnostic.lua b/runtime/lua/vim/lsp/diagnostic.lua index 904ef611c0..eab69fdc62 100644 --- a/runtime/lua/vim/lsp/diagnostic.lua +++ b/runtime/lua/vim/lsp/diagnostic.lua @@ -460,12 +460,12 @@ function M._enable(bufnr) api.nvim_create_autocmd('LspDetach', { buffer = bufnr, - callback = function(args) + callback = function(ev) local clients = lsp.get_clients({ bufnr = bufnr, method = 'textDocument/diagnostic' }) if not vim.iter(clients):any(function(c) - return c.id ~= args.data.client_id + return c.id ~= ev.data.client_id end) then disable(bufnr) diff --git a/runtime/lua/vim/lsp/document_color.lua b/runtime/lua/vim/lsp/document_color.lua index a48ae0350f..0b9e1a415c 100644 --- a/runtime/lua/vim/lsp/document_color.lua +++ b/runtime/lua/vim/lsp/document_color.lua @@ -218,14 +218,14 @@ local function buf_enable(bufnr) buffer = bufnr, group = document_color_augroup, desc = 'Refresh document_color on document changes', - callback = function(args) - local method = args.data.method --- @type string + callback = function(ev) + local method = ev.data.method --- @type string if (method == 'textDocument/didChange' or method == 'textDocument/didOpen') - and assert(bufstates[args.buf]).enabled + and assert(bufstates[ev.buf]).enabled then - M._buf_refresh(args.buf, args.data.client_id) + M._buf_refresh(ev.buf, ev.data.client_id) end end, }) @@ -234,16 +234,16 @@ local function buf_enable(bufnr) buffer = bufnr, group = document_color_augroup, desc = 'Disable document_color if all supporting clients detach', - callback = function(args) - local clients = lsp.get_clients({ bufnr = args.buf, method = 'textDocument/documentColor' }) + callback = function(ev) + local clients = lsp.get_clients({ bufnr = ev.buf, method = 'textDocument/documentColor' }) if not vim.iter(clients):any(function(c) - return c.id ~= args.data.client_id + return c.id ~= ev.data.client_id end) then -- There are no clients left in the buffer that support document color, so turn it off. - buf_disable(args.buf) + buf_disable(ev.buf) end end, }) diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua index 5059286f54..2e223edcd4 100644 --- a/runtime/lua/vim/lsp/inlay_hint.lua +++ b/runtime/lua/vim/lsp/inlay_hint.lua @@ -264,26 +264,23 @@ local function _enable(bufnr) end api.nvim_create_autocmd('LspNotify', { - callback = function(args) + callback = function(ev) ---@type integer - local bufnr = args.buf + local bufnr = ev.buf - if - args.data.method ~= 'textDocument/didChange' - and args.data.method ~= 'textDocument/didOpen' - then + if ev.data.method ~= 'textDocument/didChange' and ev.data.method ~= 'textDocument/didOpen' then return end if bufstates[bufnr].enabled then - refresh(bufnr, args.data.client_id) + refresh(bufnr, ev.data.client_id) end end, group = augroup, }) api.nvim_create_autocmd('LspAttach', { - callback = function(args) + callback = function(ev) ---@type integer - local bufnr = args.buf + local bufnr = ev.buf api.nvim_buf_attach(bufnr, false, { on_reload = function(_, cb_bufnr) @@ -302,13 +299,13 @@ api.nvim_create_autocmd('LspAttach', { group = augroup, }) api.nvim_create_autocmd('LspDetach', { - callback = function(args) + callback = function(ev) ---@type integer - local bufnr = args.buf + local bufnr = ev.buf local clients = vim.lsp.get_clients({ bufnr = bufnr, method = 'textDocument/inlayHint' }) if not vim.iter(clients):any(function(c) - return c.id ~= args.data.client_id + return c.id ~= ev.data.client_id end) then _disable(bufnr) end diff --git a/runtime/lua/vim/lsp/linked_editing_range.lua b/runtime/lua/vim/lsp/linked_editing_range.lua index b4070454de..c090cf7057 100644 --- a/runtime/lua/vim/lsp/linked_editing_range.lua +++ b/runtime/lua/vim/lsp/linked_editing_range.lua @@ -222,8 +222,8 @@ function LinkedEditor.new(bufnr) api.nvim_create_autocmd('LspDetach', { group = augroup, buffer = bufnr, - callback = function(args) - self:detach(args.data.client_id) + callback = function(ev) + self:detach(ev.data.client_id) end, }) diff --git a/runtime/lua/vim/lsp/on_type_formatting.lua b/runtime/lua/vim/lsp/on_type_formatting.lua index 02f64f4145..67d082410a 100644 --- a/runtime/lua/vim/lsp/on_type_formatting.lua +++ b/runtime/lua/vim/lsp/on_type_formatting.lua @@ -161,8 +161,8 @@ local function attach(client, bufnr) buffer = bufnr, desc = 'Detach on-type formatting module when the client detaches', group = augroup, - callback = function(args) - local detached_client = assert(lsp.get_client_by_id(args.data.client_id)) + callback = function(ev) + local detached_client = assert(lsp.get_client_by_id(ev.data.client_id)) detach(detached_client, bufnr) end, }) @@ -230,8 +230,8 @@ end --- --- -- Enable for a specific client --- vim.api.nvim_create_autocmd('LspAttach', { ---- callback = function(args) ---- local client_id = args.data.client_id +--- callback = function(ev) +--- local client_id = ev.data.client_id --- local client = assert(vim.lsp.get_client_by_id(client_id)) --- if client.name == 'rust-analyzer' then --- vim.lsp.on_type_formatting.enable(true, { client_id = client_id }) diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua index f4732fae80..65a405567c 100644 --- a/runtime/lua/vim/lsp/semantic_tokens.lua +++ b/runtime/lua/vim/lsp/semantic_tokens.lua @@ -1010,9 +1010,9 @@ end --- mark will be deleted by the semantic token engine when appropriate; for --- example, when the LSP sends updated tokens. This function is intended for --- use inside |LspTokenUpdate| callbacks. ----@param token (table) A semantic token, found as `args.data.token` in |LspTokenUpdate| ----@param bufnr (integer) The buffer to highlight, or `0` for current buffer ----@param client_id (integer) The ID of the |vim.lsp.Client| +---@param token (table) Semantic token, provided as `ev.data.token` in |LspTokenUpdate| +---@param bufnr (integer) Buffer to highlight, or `0` for current buffer. +---@param client_id (integer) ID of the |vim.lsp.Client| ---@param hl_group (string) Highlight group name ---@param opts? vim.lsp.semantic_tokens.highlight_token.Opts Optional parameters: function M.highlight_token(token, bufnr, client_id, hl_group, opts) diff --git a/runtime/lua/vim/termcap.lua b/runtime/lua/vim/termcap.lua index 887fd5b58f..937fee1024 100644 --- a/runtime/lua/vim/termcap.lua +++ b/runtime/lua/vim/termcap.lua @@ -33,8 +33,8 @@ function M.query(caps, cb) local id = vim.api.nvim_create_autocmd('TermResponse', { nested = true, - callback = function(args) - local resp = args.data.sequence ---@type string + callback = function(ev) + local resp = ev.data.sequence ---@type string local k, rest = resp:match('^\027P1%+r(%x+)(.*)$') if k and rest then local cap = vim.text.hexdecode(k) diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index e7aaf23ea7..6521d1c626 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -438,9 +438,9 @@ end --- --- ```lua --- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', ---- callback = function(args) ---- vim.treesitter.start(args.buf, 'latex') ---- vim.bo[args.buf].syntax = 'ON' -- only if additional legacy syntax is needed +--- callback = function(ev) +--- vim.treesitter.start(ev.buf, 'latex') +--- vim.bo[ev.buf].syntax = 'ON' -- only if additional legacy syntax is needed --- end --- }) --- ``` diff --git a/runtime/lua/vim/ui/clipboard/osc52.lua b/runtime/lua/vim/ui/clipboard/osc52.lua index 0f6016c6e8..b0164accea 100644 --- a/runtime/lua/vim/ui/clipboard/osc52.lua +++ b/runtime/lua/vim/ui/clipboard/osc52.lua @@ -23,8 +23,8 @@ function M.paste(reg) return function() local contents = nil --- @type string? local id = vim.api.nvim_create_autocmd('TermResponse', { - callback = function(args) - local resp = args.data.sequence ---@type string + callback = function(ev) + local resp = ev.data.sequence ---@type string local encoded = resp:match('\027%]52;%w?;([A-Za-z0-9+/=]*)') if encoded then contents = vim.base64.decode(encoded) diff --git a/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua b/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua index 539b7ee750..1de4f77d93 100644 --- a/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua +++ b/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua @@ -447,20 +447,20 @@ function M.open(left, right, opt) vim.api.nvim_create_autocmd('BufWinEnter', { group = layout.group, pattern = 'quickfix', - callback = function(args) + callback = function(ev) if not get_diff_entry() then return end - vim.api.nvim_buf_clear_namespace(args.buf, hl_id, 0, -1) - local lines = vim.api.nvim_buf_get_lines(args.buf, 0, -1, false) + vim.api.nvim_buf_clear_namespace(ev.buf, hl_id, 0, -1) + local lines = vim.api.nvim_buf_get_lines(ev.buf, 0, -1, false) -- Map status codes to highlight groups for i, line in ipairs(lines) do local status = line:match('^(%a) ') local hl_group = highlight_groups[status] if hl_group then - vim.hl.range(args.buf, hl_id, hl_group, { i - 1, 0 }, { i - 1, 1 }) + vim.hl.range(ev.buf, hl_id, hl_group, { i - 1, 0 }, { i - 1, 1 }) end end end, @@ -469,8 +469,8 @@ function M.open(left, right, opt) vim.api.nvim_create_autocmd('BufWinEnter', { group = layout.group, pattern = '*', - callback = function(args) - local entry = get_diff_entry(args.buf) + callback = function(ev) + local entry = get_diff_entry(ev.buf) if not entry then return end diff --git a/runtime/plugin/editorconfig.lua b/runtime/plugin/editorconfig.lua index 357146cabd..5566329f72 100644 --- a/runtime/plugin/editorconfig.lua +++ b/runtime/plugin/editorconfig.lua @@ -1,13 +1,13 @@ local group = vim.api.nvim_create_augroup('nvim.editorconfig', {}) vim.api.nvim_create_autocmd({ 'BufNewFile', 'BufRead', 'BufFilePost' }, { group = group, - callback = function(args) + callback = function(ev) -- Buffer-local enable has higher priority local enable = vim.F.if_nil(vim.b.editorconfig, vim.g.editorconfig, true) if not enable then return end - require('editorconfig').config(args.buf) + require('editorconfig').config(ev.buf) end, }) diff --git a/runtime/plugin/nvim/net.lua b/runtime/plugin/nvim/net.lua index 4281557c0d..e23c55a115 100644 --- a/runtime/plugin/nvim/net.lua +++ b/runtime/plugin/nvim/net.lua @@ -1,8 +1,8 @@ vim.g.loaded_remote_file_loader = true --- Callback for BufReadCmd on remote URLs. ---- @param args { buf: integer } -local function on_remote_read(args) +--- @param ev { buf: integer } +local function on_remote_read(ev) if vim.fn.executable('curl') ~= 1 then vim.api.nvim_echo({ { 'Warning: `curl` not found; remote URL loading disabled.', 'WarningMsg' }, @@ -10,7 +10,7 @@ local function on_remote_read(args) return true end - local bufnr = args.buf + local bufnr = ev.buf local url = vim.api.nvim_buf_get_name(bufnr) local view = vim.fn.winsaveview() diff --git a/runtime/plugin/osc52.lua b/runtime/plugin/osc52.lua index 370dafbb4e..a17ce14f5a 100644 --- a/runtime/plugin/osc52.lua +++ b/runtime/plugin/osc52.lua @@ -36,8 +36,8 @@ vim.api.nvim_create_autocmd('UIEnter', { vim.api.nvim_create_autocmd('TermResponse', { group = id, nested = true, - callback = function(args) - local resp = args.data.sequence ---@type string + callback = function(ev) + local resp = ev.data.sequence ---@type string local params = resp:match('^\027%[%?([%d;]+)c$') if params then -- Check termfeatures again, it may have changed between the query and response. diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 9cd17b9a3a..d62cdf7e54 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -679,8 +679,8 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| if a buffer called - {buf} exists. + Checks whether a buffer with the name or number {buf} exists. + Returns |TRUE| if the buffer exists, |FALSE| otherwise. If the {buf} argument is a number, buffer numbers are used. Number zero is the alternate buffer for the current window. @@ -749,8 +749,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| if a buffer called - {buf} exists and is listed (has the 'buflisted' option set). + Checks whether a buffer called {buf} exists and is listed + (has the 'buflisted' option set). Returns |TRUE| if so, + |FALSE| otherwise. The {buf} argument is used like with |bufexists()|. ]=], @@ -782,8 +783,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| if a buffer called - {buf} exists and is loaded (shown in a window or hidden). + Checks whether a buffer called {buf} exists and is loaded + (shown in a window or hidden). Returns |TRUE| if so, + |FALSE| otherwise. The {buf} argument is used like with |bufexists()|. ]=], @@ -862,10 +864,10 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the |window-ID| of the first - window associated with buffer {buf}. For the use of {buf}, - see |bufname()| above. If buffer {buf} doesn't exist or - there is no such window, -1 is returned. Example: >vim + Returns the |window-ID| of the first window associated with + buffer {buf}. For the use of {buf}, see |bufname()| above. + If buffer {buf} doesn't exist or there is no such window, -1 + is returned. Example: >vim echo "A window containing buffer 1 is " .. (bufwinid(1)) < @@ -1296,8 +1298,8 @@ M.funcs = { args = { 1, 2 }, base = 1, desc = [=[ - The result is a Number, which is the byte index of the column - position given with {expr}. + Returns the byte index of the column position given with + {expr}. For accepted positions see |getpos()|. When {expr} is "$", it means the end of the cursor line, so the result is the number of bytes in the cursor line plus one. @@ -2244,8 +2246,8 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| if {expr} is - defined, zero otherwise. + Checks whether the expression {expr} is defined. + Returns |TRUE| if {expr} is defined, zero otherwise. For checking for a supported feature use |has()|. For checking if a file exists use |filereadable()|. @@ -2648,12 +2650,12 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| when a file with the - name {file} exists, and can be read. If {file} doesn't exist, - or is a directory, the result is |FALSE|. {file} is any - expression, which is used as a String. - If you don't care about the file being readable you can use - |glob()|. + Returns |TRUE| if {file} exists, can be read, and is not + a directory, else |FALSE|. + + {file} is any expression, which is used as a String. If you + don't care about the file being readable you can use |glob()|. + {file} is used as-is, you may want to expand wildcards first: >vim echo filereadable('~/.vimrc') < > @@ -2675,9 +2677,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is 1 when a file with the - name {file} exists, and can be written. If {file} doesn't - exist, or is not writable, the result is 0. If {file} is a + Checks whether a file with the name {file} exists and can + be written. Returns 1 if so. If {file} doesn't exist, or + is not writable, the result is 0. If {file} is a directory, and we can write to it, the result is 2. ]=], @@ -2965,9 +2967,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number. If the line {lnum} is in a closed - fold, the result is the number of the first line in that fold. - If the line {lnum} is not in a closed fold, -1 is returned. + Returns the first line number of the closed fold containing + line {lnum}. If the line {lnum} is not in a closed fold, + -1 is returned. {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. @@ -2981,9 +2983,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number. If the line {lnum} is in a closed - fold, the result is the number of the last line in that fold. - If the line {lnum} is not in a closed fold, -1 is returned. + Returns the last line number of the closed fold containing + line {lnum}. If the line {lnum} is not in a closed fold, + -1 is returned. {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. @@ -2997,17 +2999,17 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the foldlevel of line {lnum} - in the current buffer. For nested folds the deepest level is - returned. If there is no fold at line {lnum}, zero is - returned. It doesn't matter if the folds are open or closed. - When used while updating folds (from 'foldexpr') -1 is - returned for lines where folds are still to be updated and the - foldlevel is unknown. As a special case the level of the - previous line is usually available. - {lnum} is used like with |getline()|. Thus "." is the current - line, "'m" mark m, etc. + Returns the fold nesting level of line {lnum} in the current + buffer. {lnum} is used like with |getline()| ("." is the + current line, "'m" mark m, etc). + For nested folds the deepest level is returned. If there is + no fold at line {lnum}, zero is returned. It doesn't matter + if the folds are open or closed. When used while updating + folds (from 'foldexpr') -1 is returned for lines where folds + are still to be updated and the foldlevel is unknown. As + a special case the level of the previous line is usually + available. ]=], name = 'foldlevel', params = { { 'lnum', 'integer|string' } }, @@ -3632,8 +3634,8 @@ M.funcs = { }, getcharmod = { desc = [=[ - The result is a Number which is the state of the modifiers for - the last obtained character with |getchar()| or in another way. + Returns the state of the keyboard modifiers for the last + character obtained with |getchar()| or in another way. These values are added together: 2 shift 4 control @@ -4054,10 +4056,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a String, which is the read, write, and execute - permissions of the given file {fname}. - If {fname} does not exist or its directory cannot be read, an - empty string is returned. + Returns the file permissions of the given file {fname} as a + String. If {fname} does not exist or its directory cannot be + read, an empty string is returned. The result is of the form "rwxrwxrwx", where each group of "rwx" flags represent, in turn, the permissions of the owner of the file, the group the file belongs to, and other users. @@ -4080,8 +4081,7 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the size in bytes of the - given file {fname}. + Returns the size in bytes of the given file {fname}. If {fname} is a directory, 0 is returned. If the file {fname} can't be found, -1 is returned. If the size of {fname} is too big to fit in a Number then -2 @@ -4098,9 +4098,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the last modification time of - the given file {fname}. The value is measured as seconds - since 1st Jan 1970, and may be passed to |strftime()|. See also + Returns the last modification time of the given file {fname}. + The value is measured as seconds since 1st Jan 1970, and may + be passed to |strftime()|. See also |localtime()| and |strftime()|. If the file {fname} can't be found -1 is returned. @@ -4115,9 +4115,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a String, which is a description of the kind of - file of the given file {fname}. - If {fname} does not exist an empty string is returned. + Returns a description of the type of file {fname} as a + String. If {fname} does not exist an empty string is + returned. Here is a table over different kinds of files and their results: Normal file "file" @@ -4548,8 +4548,8 @@ M.funcs = { args = { 0, 3 }, base = 1, desc = [=[ - The result is a String, which is the contents of register - {regname}. Example: >vim + Returns the contents of register {regname} as a String. + Example: >vim let cliptext = getreg('*') vim @@ -5498,11 +5497,10 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is TRUE if a highlight group - called {name} exists. This is when the group has been - defined in some way. Not necessarily when highlighting has - been defined for it, it may also have been used for a syntax - item. + Checks whether a highlight group called {name} exists. + Returns TRUE if the group has been defined in some way. Not + necessarily when highlighting has been defined for it, it may + also have been used for a syntax item. ]=], name = 'hlexists', @@ -5512,8 +5510,8 @@ M.funcs = { }, hostname = { desc = [=[ - The result is a String, which is the name of the machine on - which Vim is currently running. Machine names greater than + Returns the hostname of the machine on which the Nvim server + (not the UI client) is currently running. Names greater than 256 characters long are truncated. ]=], fast = true, @@ -5526,8 +5524,8 @@ M.funcs = { args = 3, base = 1, desc = [=[ - The result is a String, which is the text {string} converted - from encoding {from} to encoding {to}. + Converts the encoding of {string} from {from} to {to}. + Returns the converted String. When the conversion completely fails an empty string is returned. When some characters could not be converted they are replaced with "?". @@ -5572,9 +5570,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is indent of line {lnum} in the - current buffer. The indent is counted in spaces, the value - of 'tabstop' is relevant. {lnum} is used just like in + Returns the indent of line {lnum} in the current buffer. + The indent is counted in spaces, the value of 'tabstop' is + relevant. {lnum} is used just like in |getline()|. When {lnum} is invalid -1 is returned. @@ -5684,10 +5682,10 @@ M.funcs = { args = { 1, 3 }, base = 1, desc = [=[ - The result is a String, which is whatever the user typed on - the command-line. The {prompt} argument is either a prompt - string, or a blank string (for no prompt). A '\n' can be used - in the prompt to start a new line. + Prompts the user to enter text on the command-line, and + returns the text as a String. The {prompt} argument is either + a prompt string, or a blank string (for no prompt). A '\n' + can be used in the prompt to start a new line. In the second form it accepts a single dictionary with the following keys, any of which may be omitted: @@ -5814,9 +5812,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - {textlist} must be a |List| of strings. This |List| is - displayed, one string per line. The user will be prompted to - enter a number, which is returned. + Displays a list of strings and prompts the user to select + one by entering a number. {textlist} must be a |List| of + strings. Returns the number the user entered. The user can also select an item by clicking on it with the mouse, if the mouse is enabled in the command line ('mouse' is "a" or includes "c"). For the first string 0 is returned. @@ -5945,8 +5943,8 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| when {path} is an - absolute path. + Checks whether {path} is an absolute path. Returns |TRUE| + if so, |FALSE| otherwise. On Unix, a path is considered absolute when it starts with '/'. On MS-Windows, it is considered absolute when it starts with @@ -5970,10 +5968,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| when a directory - with the name {directory} exists. If {directory} doesn't - exist, or isn't a directory, the result is |FALSE|. {directory} - is any expression, which is used as a String. + Returns |TRUE| if {directory} exists, or |FALSE| if it doesn't + exist or isn't a directory. {directory} is any expression, + which is used as a String. ]=], fast = true, @@ -6003,8 +6000,8 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is |TRUE| when {expr} is the - name of a locked variable. + Returns |TRUE| if {expr} is the name of a locked variable, + else |FALSE|. The string argument {expr} must be the name of a variable, |List| item or |Dictionary| entry, not the variable itself! Example: >vim @@ -6355,7 +6352,7 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the length of the argument. + Returns the length of the argument. When {expr} is a String or a Number the length in bytes is used, as with |strlen()|. When {expr} is a |List| the number of items in the |List| is @@ -9127,11 +9124,11 @@ M.funcs = { args = 2, base = 1, desc = [=[ - The result is a Number, which is the character at position - [row, col] on the screen. This works for every possible - screen position, also status lines, window separators and the - command line. The top left position is row one, column one - The character excludes composing characters. For double-byte + Returns the character at screen position [row, col] as a + Number. This works for every possible screen position, also + status lines, window separators and the command line. The + top left position is row one, column one. The character + excludes composing characters. For double-byte encodings it may only be the first byte. This is mainly to be used for testing. Returns -1 when row or col is out of range. @@ -9146,9 +9143,10 @@ M.funcs = { args = 2, base = 1, desc = [=[ - The result is a |List| of Numbers. The first number is the same - as what |screenchar()| returns. Further numbers are - composing characters on top of the base character. + Returns the character and any composing characters at screen + position [row, col] as a |List| of Numbers. The first number + is the same as what |screenchar()| returns; further numbers + are composing characters on top of the base character. This is mainly to be used for testing. Returns an empty List when row or col is out of range. @@ -9160,8 +9158,8 @@ M.funcs = { }, screencol = { desc = [=[ - The result is a Number, which is the current screen column of - the cursor. The leftmost column has number 1. + Returns the current screen column of the cursor. The + leftmost column has number 1. This function is mainly used for testing. Note: Always returns the current screen column, thus if used @@ -9183,9 +9181,9 @@ M.funcs = { args = 3, base = 1, desc = [=[ - The result is a Dict with the screen position of the text - character in window {winid} at buffer line {lnum} and column - {col}. {col} is a one-based byte index. + Returns the screen position of the text character in window + {winid} at buffer line {lnum} and column {col} as a Dict. + {col} is a one-based byte index. The Dict has these members: row screen row col first screen column @@ -9214,8 +9212,8 @@ M.funcs = { }, screenrow = { desc = [=[ - The result is a Number, which is the current screen row of the - cursor. The top line has number one. + Returns the current screen row of the cursor. The top line + has number one. This function is mainly used for testing. Alternatively you can use |winline()|. @@ -9230,10 +9228,9 @@ M.funcs = { args = 2, base = 1, desc = [=[ - The result is a String that contains the base character and - any composing characters at position [row, col] on the screen. - This is like |screenchars()| but returning a String with the - characters. + Returns the base character and any composing characters at + screen position [row, col] as a String. This is like + |screenchars()| but returning a String with the characters. This is mainly to be used for testing. Returns an empty String when row or col is out of range. @@ -11525,13 +11522,12 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the number of characters - in String {string}. Composing characters are ignored. + Returns the number of characters in String {string}, ignoring + composing characters. Returns 0 on error or empty {string}. + |strchars()| can count the number of characters, counting composing characters separately. - Returns 0 if {string} is empty or on error. - Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. ]=], @@ -11574,8 +11570,7 @@ M.funcs = { args = { 1, 2 }, base = 1, desc = [=[ - The result is a Number, which is the number of characters - in String {string}. + Returns the number of characters in String {string}. When {skipcc} is omitted or zero, composing characters are counted separately. When {skipcc} set to 1, composing characters are ignored. @@ -11611,18 +11606,20 @@ M.funcs = { args = { 1, 2 }, base = 1, desc = [=[ - The result is a Number, which is the number of display cells - String {string} occupies on the screen when it starts at {col} - (first column is zero). When {col} is omitted zero is used. - Otherwise it is the screen column where to start. This - matters for Tab characters. + Returns the number of display cells String {string} occupies + on the screen when it starts at {col} (first column is zero). + Returns zero on error. + + When {col} is omitted zero is used. Otherwise it is the screen + column where to start. This matters for Tab characters. The option settings of the current window are used. This matters for anything that's displayed differently, such as 'tabstop' and 'display'. + When {string} contains characters with East Asian Width Class Ambiguous, this function's return value depends on 'ambiwidth'. - Returns zero on error. + Also see |strlen()|, |strwidth()| and |strchars()|. ]=], @@ -11635,10 +11632,9 @@ M.funcs = { args = { 1, 2 }, base = 1, desc = [=[ - The result is a String, which is a formatted date and time, as - specified by the {format} string. The given {time} is used, - or the current time if no time is given. The accepted - {format} depends on your system, thus this is not portable! + Formats a date and time String specified by {format}. The + given {time} is used, or the current time if no time is given. + The {format} depends on your system, this is not portable! See the manual page of the C function strftime() for the format. The maximum length of the result is 80 characters. See also |localtime()|, |getftime()| and |strptime()|. @@ -11679,8 +11675,8 @@ M.funcs = { args = { 2, 3 }, base = 1, desc = [=[ - The result is a Number, which gives the byte index in - {haystack} of the first occurrence of the String {needle}. + Returns the byte index of the first occurrence of {needle} + in {haystack}. If {start} is specified, the search starts at index {start}. This can be used to find a second match: >vim let colon1 = stridx(line, ":") @@ -11708,9 +11704,10 @@ M.funcs = { args = 1, base = 1, desc = [=[ - Return {expr} converted to a String. If {expr} is a Number, - Float, String, Blob or a composition of them, then the result - can be parsed back with |eval()|. + Converts {expr} to a String. If {expr} is a Number, Float, + String, Blob or a composition of them, the result can be + parsed back with |eval()|. + {expr} type result ~ String 'string' Number 123 @@ -11720,14 +11717,16 @@ M.funcs = { Blob 0z00112233.44556677.8899 List [item, item] Dictionary `{key: value, key: value}` - Note that in String values the ' character is doubled. + + Note: in String values the ' character is doubled. Also see |strtrans()|. - Note 2: Output format is mostly compatible with YAML, except - for infinite and NaN floating-point values representations - which use |str2float()|. Strings are also dumped literally, - only single quote is escaped, which does not allow using YAML - for parsing back binary strings. |eval()| should always work - for strings and floats though, and this is the only official + + Note: Output format is mostly compatible with YAML, except for + infinite and NaN floating-point values representations which + use |str2float()|. Strings are also dumped literally, only + single quote is escaped, which does not allow using YAML for + parsing back binary strings. |eval()| should always work for + strings and floats though, and this is the only official method. Use |msgpackdump()| or |json_encode()| if you need to share data with other applications. @@ -11741,8 +11740,7 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the length of the String - {string} in bytes. + Returns the length of String {string} in bytes. If the argument is a Number it is first converted to a String. For other types an error is given and zero is returned. If you want to count the number of multibyte characters use @@ -11759,12 +11757,14 @@ M.funcs = { args = { 2, 4 }, base = 1, desc = [=[ - The result is a String, which is part of {src}, starting from - byte {start}, with the byte length {len}. + Gets a substring from {src}, starting from byte {start}, with + byte length {len}. Returns empty string on error. + When {chars} is present and TRUE then {len} is the number of characters positions (composing characters are not counted separately, thus "1" means one base character and any following composing characters). + To count {start} as characters instead of bytes use |strcharpart()|. @@ -11781,7 +11781,6 @@ M.funcs = { example, to get the character under the cursor: >vim strpart(getline("."), col(".") - 1, 1, v:true) < - Returns an empty string on error. ]=], fast = true, @@ -11799,14 +11798,12 @@ M.funcs = { args = 2, base = 1, desc = [=[ - The result is a Number, which is a unix timestamp representing - the date and time in {timestring}, which is expected to match - the format specified in {format}. + Parses a date/time string and returns a unix timestamp. + {timestring} must match the format specified in {format}. - The accepted {format} depends on your system, thus this is not - portable! See the manual page of the C function strptime() - for the format. Especially avoid "%c". The value of $TZ also - matters. + The {format} depends on your system, this is not portable! + See the strptime() manpage for the format. Especially avoid + "%c". The value of $TZ also matters. If the {timestring} cannot be parsed with {format} zero is returned. If you do not know the format of {timestring} you @@ -11832,8 +11829,8 @@ M.funcs = { args = { 2, 3 }, base = 1, desc = [=[ - The result is a Number, which gives the byte index in - {haystack} of the last occurrence of the String {needle}. + Returns the byte index of the last occurrence of {needle} + in {haystack}. When {start} is specified, matches beyond this index are ignored. This can be used to find a match before a previous match: >vim @@ -11863,9 +11860,9 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a String, which is {string} with all unprintable - characters translated into printable characters 'isprint'. - Like they are shown in a window. Example: >vim + Translates all unprintable characters in {string} into + printable characters 'isprint', like they are shown in a + window. Example: >vim echo strtrans(@a) at the + Returns the virtual (screen) column of the file position + given with {expr}. That is, the total number of screen cells + occupied by the part of the line until the end of the + character at that position. When there is a at the position, the returned Number will be the column at the end of the . For example, for a in column 1, with 'ts' set to 8, it returns 8. |conceal| is ignored. @@ -13030,9 +13023,9 @@ M.funcs = { args = 3, base = 1, desc = [=[ - The result is a Number, which is the byte index of the - character in window {winid} at buffer line {lnum} and virtual - column {col}. + Converts a virtual column to a byte index. Returns the byte + index of the character in window {winid} at buffer line + {lnum} and virtual column {col}. If buffer line {lnum} is an empty line, 0 is returned. @@ -13060,9 +13053,9 @@ M.funcs = { visualmode = { args = { 0, 1 }, desc = [=[ - The result is a String, which describes the last Visual mode - used in the current buffer. Initially it returns an empty - string, but once Visual mode has been used, it returns "v", + Returns a String describing the last Visual mode used in the + current buffer. Initially it returns an empty string, but + once Visual mode has been used, it returns "v", "V", or "" (a single CTRL-V character) for character-wise, line-wise, or block-wise Visual mode respectively. @@ -13358,9 +13351,8 @@ M.funcs = { args = 1, base = 1, desc = [=[ - The result is a Number, which is the number of the buffer - associated with window {nr}. {nr} can be the window number or - the |window-ID|. + Returns the buffer number associated with window {nr}. + {nr} can be the window number or the |window-ID|. When {nr} is zero, the number of the buffer in the current window is returned. When window {nr} doesn't exist, -1 is returned. @@ -13375,9 +13367,9 @@ M.funcs = { }, wincol = { desc = [=[ - The result is a Number, which is the virtual column of the - cursor in the window. This is counting screen cells from the - left side of the window. The leftmost column is one. + Returns the virtual column of the cursor in the window. + This is counting screen cells from the left side of the + window. The leftmost column is one. ]=], name = 'wincol', params = {}, @@ -13386,10 +13378,11 @@ M.funcs = { }, windowsversion = { desc = [=[ - The result is a String. For MS-Windows it indicates the OS - version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", - Windows XP is "5.1". For non-MS-Windows systems the result is - an empty string. + Returns the Windows OS version as a String. E.g, Windows 10 + is "10.0", Windows 8 is "6.2", Windows XP is "5.1". For + non-MS-Windows systems the result is an empty string. + + See also Lua |uv.os_uname()|. ]=], fast = true, name = 'windowsversion', @@ -13419,8 +13412,7 @@ M.funcs = { args = { 0, 1 }, base = 1, desc = [=[ - The result is a nested List containing the layout of windows - in a tabpage. + Returns the layout of windows in a tabpage as a nested List. Without {tabnr} use the current tabpage, otherwise the tabpage with number {tabnr}. If the tabpage {tabnr} is not found, @@ -13462,9 +13454,9 @@ M.funcs = { }, winline = { desc = [=[ - The result is a Number, which is the screen line of the cursor - in the window. This is counting screen lines from the top of - the window. The first line is one. + Returns the screen line of the cursor in the window. This is + counting screen lines from the top of the window. The first + line is one. If the cursor was moved the view on the file will be updated first, this may cause a scroll. ]=], @@ -13477,10 +13469,9 @@ M.funcs = { args = { 0, 1 }, base = 1, desc = [=[ - The result is a Number, which is the number of the current - window. The top window has number 1. - Returns zero for a hidden or non |focusable| window, unless - it is the current window. + Returns the number of the current window. The top window has + number 1. Returns zero for a hidden or non |focusable| + window, unless it is the current window. The optional argument {arg} supports the following values: $ the number of the last window (the window @@ -13616,9 +13607,8 @@ M.funcs = { }, wordcount = { desc = [=[ - The result is a dictionary of byte/chars/word statistics for - the current buffer. This is the same info as provided by - |g_CTRL-G| + Returns a dictionary of byte/chars/word statistics for the + current buffer. This is the same info provided by |g_CTRL-G|. The return value includes: bytes Number of bytes in the buffer chars Number of chars in the buffer diff --git a/src/nvim/normal.c b/src/nvim/normal.c index 3e4e604520..9f10876a11 100644 --- a/src/nvim/normal.c +++ b/src/nvim/normal.c @@ -1330,7 +1330,7 @@ static void normal_check_text_changed(NormalState *s) static void normal_check_buffer_modified(NormalState *s) { - // Trigger BufModified if b_modified changed + // Trigger BufModified if 'modified' changed. if (!finish_op && has_event(EVENT_BUFMODIFIEDSET) && curbuf->b_changed_invalid == true) { apply_autocmds(EVENT_BUFMODIFIEDSET, NULL, NULL, false, curbuf); diff --git a/src/nvim/options.lua b/src/nvim/options.lua index 20ec24d22d..480e4b22e9 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -5935,11 +5935,13 @@ local options = { result of a BufNewFile, BufRead/BufReadPost, BufWritePost, FileAppendPost or VimLeave autocommand event. See |gzip-example| for an explanation. + + When 'buftype' is "prompt", 'modified' is not implicitly set when the + buffer is changed, but a user or plugin may explicitly set it. + When 'buftype' is "nowrite" or "nofile", this option may be set, but - it is ignored and will not block closing the window. For "prompt" - buffers, changes made to the buffer do not make it count as modified, - but an explicit ":set modified" is respected and will block closing the - window. + will be ignored. + Note that the text may actually be the same, e.g. 'modified' is set when using "rA" on an "A". ]=], diff --git a/test/functional/api/autocmd_spec.lua b/test/functional/api/autocmd_spec.lua index 10e4a45254..2324b9ffea 100644 --- a/test/functional/api/autocmd_spec.lua +++ b/test/functional/api/autocmd_spec.lua @@ -351,8 +351,8 @@ describe('autocmd api', function() local output vim.api.nvim_create_autocmd("User", { pattern = "Test", - callback = function(args) - output = args.data + callback = function(ev) + output = ev.data end, }) diff --git a/test/functional/lua/buffer_updates_spec.lua b/test/functional/lua/buffer_updates_spec.lua index e87407f176..e1a46589f2 100644 --- a/test/functional/lua/buffer_updates_spec.lua +++ b/test/functional/lua/buffer_updates_spec.lua @@ -1776,14 +1776,10 @@ describe('nvim_buf_attach on_detach', function() it('called before buf_freeall autocommands', function() exec_lua(function() vim.api.nvim_create_autocmd({ 'BufUnload', 'BufDelete', 'BufWipeout' }, { - callback = function(args) + callback = function(ev) table.insert( _G.events, - ('%s: %d %s'):format( - args.event, - args.buf, - tostring(vim.api.nvim_buf_is_loaded(args.buf)) - ) + ('%s: %d %s'):format(ev.event, ev.buf, tostring(vim.api.nvim_buf_is_loaded(ev.buf))) ) end, }) diff --git a/test/functional/lua/diagnostic_spec.lua b/test/functional/lua/diagnostic_spec.lua index 37939370b2..7ec6387ca4 100644 --- a/test/functional/lua/diagnostic_spec.lua +++ b/test/functional/lua/diagnostic_spec.lua @@ -2877,9 +2877,9 @@ describe('vim.diagnostic', function() local changed_diags --- @type vim.Diagnostic[]? vim.api.nvim_create_autocmd('DiagnosticChanged', { buffer = _G.diagnostic_bufnr, - callback = function(args) + callback = function(ev) --- @type vim.Diagnostic[] - changed_diags = args.data.diagnostics + changed_diags = ev.data.diagnostics end, }) vim.diagnostic.set(_G.diagnostic_ns, _G.diagnostic_bufnr, {}) @@ -4322,8 +4322,8 @@ describe('vim.diagnostic', function() local triggered = {} vim.api.nvim_create_autocmd('DiagnosticChanged', { - callback = function(args) - triggered = { args.buf, #args.data.diagnostics } + callback = function(ev) + triggered = { ev.buf, #ev.data.diagnostics } end, }) vim.api.nvim_buf_set_name(_G.diagnostic_bufnr, 'test | test') diff --git a/test/functional/plugin/lsp/semantic_tokens_spec.lua b/test/functional/plugin/lsp/semantic_tokens_spec.lua index 92e00a8888..eb9e2abaca 100644 --- a/test/functional/plugin/lsp/semantic_tokens_spec.lua +++ b/test/functional/plugin/lsp/semantic_tokens_spec.lua @@ -501,10 +501,10 @@ describe('semantic token highlighting', function() insert(text) exec_lua(function() vim.api.nvim_create_autocmd('LspTokenUpdate', { - callback = function(args) - local token = args.data.token --- @type STTokenRange + callback = function(ev) + local token = ev.data.token --- @type STTokenRange if token.type == 'function' and token.modifiers.declaration then - vim.lsp.semantic_tokens.highlight_token(token, args.buf, args.data.client_id, 'Macro') + vim.lsp.semantic_tokens.highlight_token(token, ev.buf, ev.data.client_id, 'Macro') end end, }) diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua index d44f064027..69da90dd68 100644 --- a/test/functional/plugin/lsp_spec.lua +++ b/test/functional/plugin/lsp_spec.lua @@ -408,14 +408,14 @@ describe('LSP', function() exec_lua(function() _G.BUFFER = vim.api.nvim_create_buf(false, true) vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - local client0 = assert(vim.lsp.get_client_by_id(args.data.client_id)) + callback = function(ev) + local client0 = assert(vim.lsp.get_client_by_id(ev.data.client_id)) vim.g.lsp_attached = client0.name end, }) vim.api.nvim_create_autocmd('LspDetach', { - callback = function(args) - local client0 = assert(vim.lsp.get_client_by_id(args.data.client_id)) + callback = function(ev) + local client0 = assert(vim.lsp.get_client_by_id(ev.data.client_id)) vim.g.lsp_detached = client0.name end, }) diff --git a/test/functional/terminal/buffer_spec.lua b/test/functional/terminal/buffer_spec.lua index 40d4dbfaa3..f868cfe539 100644 --- a/test/functional/terminal/buffer_spec.lua +++ b/test/functional/terminal/buffer_spec.lua @@ -422,12 +422,12 @@ describe(':terminal buffer', function() exec_lua(function() _G.last_event = nil vim.api.nvim_create_autocmd({ 'TermEnter', 'TermLeave' }, { - callback = function(args) - _G.last_event = args.event + callback = function(ev) + _G.last_event = ev.event .. ' ' - .. vim.fs.basename(args.file) + .. vim.fs.basename(ev.file) .. ' ' - .. tostring(vim.b[args.buf].term_focused) + .. tostring(vim.b[ev.buf].term_focused) end, }) end) @@ -706,8 +706,8 @@ describe(':terminal buffer', function() force_crlf = false, }) vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - if args.data.sequence == '\027]11;?' then + callback = function(ev) + if ev.data.sequence == '\027]11;?' then table.insert(_G.input, '\027]11;rgb:0000/0000/0000\027\\') end end @@ -758,8 +758,8 @@ describe(':terminal buffer', function() _G.cursor = {} local term = vim.api.nvim_open_term(0, {}) vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - _G.cursor = args.data.cursor + callback = function(ev) + _G.cursor = ev.data.cursor end }) return term diff --git a/test/functional/terminal/parser_spec.lua b/test/functional/terminal/parser_spec.lua index e3cfa243c2..62292eb31c 100644 --- a/test/functional/terminal/parser_spec.lua +++ b/test/functional/terminal/parser_spec.lua @@ -67,8 +67,8 @@ describe(':terminal', function() local chan = api.nvim_open_term(0, {}) exec_lua([[ vim.api.nvim_create_autocmd("TermRequest", { - callback = function(args) - _G.osc10_response = {sequence = args.data.sequence, terminator = args.data.terminator } + callback = function(ev) + _G.osc10_response = {sequence = ev.data.sequence, terminator = ev.data.terminator } end }) ]]) diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua index a9203bd41f..6a18ae96cf 100644 --- a/test/functional/terminal/tui_spec.lua +++ b/test/functional/terminal/tui_spec.lua @@ -2672,8 +2672,8 @@ describe('TUI', function() _G.urls = {} vim.api.nvim_create_autocmd('TermRequest', { buffer = buf, - callback = function(args) - local req = args.data.sequence + callback = function(ev) + local req = ev.data.sequence if not req then return end @@ -3733,14 +3733,14 @@ describe('TUI', function() clear() exec_lua([[ vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - local req = args.data.sequence + callback = function(ev) + local req = ev.data.sequence local sequence = req:match('^\027P%+q([%x;]+)$') if sequence then local t = {} for cap in vim.gsplit(sequence, ';') do local resp = string.format('\027P1+r%s\027\\', sequence) - vim.api.nvim_chan_send(vim.bo[args.buf].channel, resp) + vim.api.nvim_chan_send(vim.bo[ev.buf].channel, resp) t[vim.text.hexdecode(cap)] = true end vim.g.xtgettcap = t @@ -3784,15 +3784,15 @@ describe('TUI', function() clear() exec_lua([[ vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - local req = args.data.sequence + callback = function(ev) + local req = ev.data.sequence vim.g.termrequest = req local xtgettcap = req:match('^\027P%+q([%x;]+)$') if xtgettcap then local t = {} for cap in vim.gsplit(xtgettcap, ';') do local resp = string.format('\027P1+r%s\027\\', xtgettcap) - vim.api.nvim_chan_send(vim.bo[args.buf].channel, resp) + vim.api.nvim_chan_send(vim.bo[ev.buf].channel, resp) t[vim.text.hexdecode(cap)] = true end vim.g.xtgettcap = t @@ -3852,12 +3852,12 @@ describe('TUI', function() exec_lua([[ _G.query = false vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - local req = args.data.sequence + callback = function(ev) + local req = ev.data.sequence local sequence = req:match('^\027P%+q([%x;]+)$') if sequence and vim.text.hexdecode(sequence) == 'Ms' then local resp = string.format('\027P1+r%s=%s\027\\', sequence, vim.text.hexencode('\027]52;;\027\\')) - vim.api.nvim_chan_send(vim.bo[args.buf].channel, resp) + vim.api.nvim_chan_send(vim.bo[ev.buf].channel, resp) _G.query = true return true end @@ -3908,8 +3908,8 @@ describe('TUI', function() -- Check that we do not emit an XTGETTCAP request when DA1 indicates support _G.query = false vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - local req = args.data.sequence + callback = function(ev) + local req = ev.data.sequence local sequence = req:match('^\027P%+q([%x;]+)$') if sequence and vim.text.hexdecode(sequence) == 'Ms' then _G.query = true @@ -3944,8 +3944,8 @@ describe('TUI', function() exec_lua([[ _G.query = false vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - local req = args.data.sequence + callback = function(ev) + local req = ev.data.sequence local sequence = req:match('^\027P%+q([%x;]+)$') if sequence and vim.text.hexdecode(sequence) == 'Ms' then _G.query = true @@ -4026,8 +4026,8 @@ describe('TUI bg color', function() it('queries the terminal for background color', function() exec_lua([[ vim.api.nvim_create_autocmd('TermRequest', { - callback = function(args) - local req = args.data.sequence + callback = function(ev) + local req = ev.data.sequence if req == '\027]11;?' then vim.g.oscrequest = true return true