From 1c324cb1927e03b5a3584a8982e3d5029498f14e Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 11 Dec 2022 21:41:26 -0500 Subject: [PATCH] docs #20986 - https://github.com/neovim/tree-sitter-vimdoc v1.2.4 eliminates most errors in pi_netrw.txt, so we can remove that workaround from ignore_parse_error(). - improved codeblock --- README.md | 10 +-- runtime/doc/api.txt | 97 ++++++++----------------- runtime/doc/develop.txt | 31 +++++--- runtime/doc/editing.txt | 44 +++++++---- runtime/doc/eval.txt | 14 ++-- runtime/doc/lsp.txt | 6 +- runtime/doc/nvim.txt | 2 +- runtime/doc/provider.txt | 2 +- runtime/doc/vim_diff.txt | 29 ++++++-- runtime/lua/vim/lsp/semantic_tokens.lua | 1 - scripts/gen_help_html.lua | 11 ++- src/nvim/api/autocmd.c | 92 +++++++---------------- test/functional/api/autocmd_spec.lua | 12 +-- 13 files changed, 156 insertions(+), 195 deletions(-) diff --git a/README.md b/README.md index 7f06455cfc..227b028c01 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Neovim -[Documentation](https://neovim.io/doc/general/) | +[Documentation](https://neovim.io/doc/) | [Chat](https://app.element.io/#/room/#neovim:matrix.org) | [Twitter](https://twitter.com/Neovim) @@ -107,9 +107,9 @@ Apache 2.0 license, except for contributions copied from Vim (identified by the encouraged to make a donation for needy children in Uganda. Please see the kcc section of the vim docs or visit the ICCF web site, available at these URLs: - http://iccf-holland.org/ - http://www.vim.org/iccf/ - http://www.iccf.nl/ + https://iccf-holland.org/ + https://www.vim.org/iccf/ + https://www.iccf.nl/ You can also sponsor the development of Vim. Vim sponsors can vote for features. The money goes to Uganda anyway. @@ -121,7 +121,7 @@ Apache 2.0 license, except for contributions copied from Vim (identified by the [advanced UIs]: https://github.com/neovim/neovim/wiki/Related-projects#gui [Managed packages]: https://github.com/neovim/neovim/wiki/Installing-Neovim#install-from-package [Debian]: https://packages.debian.org/testing/neovim -[Ubuntu]: http://packages.ubuntu.com/search?keywords=neovim +[Ubuntu]: https://packages.ubuntu.com/search?keywords=neovim [Fedora]: https://packages.fedoraproject.org/pkgs/neovim/neovim/ [Arch Linux]: https://www.archlinux.org/packages/?q=neovim [Void Linux]: https://voidlinux.org/packages/?arch=x86_64&q=neovim diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index decd3ca7d3..6659e9b79b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3228,89 +3228,54 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* |autocmd-groups| nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* - Create an |autocommand| - - The API allows for two (mutually exclusive) types of actions to be - executed when the autocommand triggers: a callback function (Lua or - Vimscript), or a command (like regular autocommands). - - Example using callback: >lua - -- Lua function - local myluafun = function() print("This buffer enters") end - - -- Vimscript function name (as a string) - local myvimfun = "g:MyVimFunction" + Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). + Example using Lua callback: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { pattern = {"*.c", "*.h"}, - callback = myluafun, -- Or myvimfun + callback = function(ev) + print(string.format('event fired: s', vim.inspect(ev))) + end }) < - Lua functions receive a table with information about the autocmd event as - an argument. To use a function which itself accepts another (optional) - parameter, wrap the function in a lambda: >lua - -- Lua function with an optional parameter. - -- The autocmd callback would pass a table as argument but this - -- function expects number|nil - local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end - - vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { - pattern = {"*.c", "*.h"}, - callback = function() myluafun() end, - }) -< - - Example using command: >lua + Example using an Ex command as the handler: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { pattern = {"*.c", "*.h"}, command = "echo 'Entering a C or C++ file'", }) < - Example values for pattern: >lua - pattern = "*.py" - pattern = { "*.py", "*.pyi" } -< - - Note: The `pattern` is passed to callbacks and commands as a literal string; environment - variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead, - |expand()| such variables explicitly: >lua + Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like + "$HOME" and "~" must be expanded explicitly: >lua pattern = vim.fn.expand("~") .. "/some/path/*.py" < - Example values for event: >lua - event = "BufWritePre" - event = {"CursorHold", "BufWritePre", "BufWritePost"} -< - Parameters: ~ - • {event} (string|array) The event or events to register this - autocommand - • {opts} Dictionary of autocommand options: - • group (string|integer) optional: the autocommand group name - or id to match against. - • pattern (string|array) optional: pattern or patterns to - match literally against |autocmd-pattern|. - • buffer (integer) optional: buffer number for buffer local + • {event} (string|array) Event(s) that will trigger the handler + (`callback` or `command`). + • {opts} Options dict: + • group (string|integer) optional: autocommand group name or + id to match against. + • pattern (string|array) optional: pattern(s) to match + literally |autocmd-pattern|. + • buffer (integer) optional: buffer number for buffer-local autocommands |autocmd-buflocal|. Cannot be used with {pattern}. - • desc (string) optional: description of the autocommand. - • callback (function|string) optional: if a string, the name - of a Vimscript function to call when this autocommand is - triggered. Otherwise, a Lua function which is called when - this autocommand is triggered. Cannot be used with - {command}. Lua callbacks can return true to delete the - autocommand; in addition, they accept a single table - argument with the following keys: - • id: (number) the autocommand id - • event: (string) the name of the event that triggered the - autocommand |autocmd-events| - • group: (number|nil) the autocommand group id, if it - exists - • match: (string) the expanded value of || - • buf: (number) the expanded value of || - • file: (string) the expanded value of || + • desc (string) optional: description (for documentation and + troubleshooting). + • callback (function|string) optional: Lua function (or + Vimscript function name, if string) called when the + event(s) is triggered. Lua callback can return true to + delete the autocommand, and receives a table argument with + these keys: + • id: (number) autocommand id + • event: (string) name of the triggered event + |autocmd-events| + • group: (number|nil) autocommand group id, if any + • match: (string) expanded value of || + • buf: (number) expanded value of || + • file: (string) expanded value of || • data: (any) arbitrary data passed to |nvim_exec_autocmds()| @@ -3322,7 +3287,7 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* autocommands |autocmd-nested|. Return: ~ - Integer id of the created autocommand. + Autocommand id (number) See also: ~ |autocommand| diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 9336321d73..ff48ae3e26 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -28,11 +28,9 @@ The Neo bits of Nvim should make it a better Vim, without becoming a completely different editor. - In matters of taste, prefer Vim/Unix tradition. If there is no relevant Vim/Unix tradition, consider the "common case". -- A feature that people do not know about is a useless feature. Don't add - obscure features, or at least add hints in documentation that they exist. -- There is no limit to the features that can be added. Selecting new features - is based on (1) what users ask for, (2) how much effort it takes to - implement and (3) someone actually implementing it. +- There is no limit to the features that can be added. Select new features + based on (1) what users ask for, (2) how much effort it takes to implement + and (3) someone actually implementing it. - Backwards compatibility is a feature. The RPC API in particular should never break. @@ -48,7 +46,7 @@ NVIM IS... WELL DOCUMENTED *design-documented* NVIM IS... FAST AND SMALL *design-speed-size* -Keep Nvim small and fast. +Keep Nvim small and fast. This directly affects versatility and usability. - Computers are becoming faster and bigger each year. Vim can grow too, but no faster than computers are growing. Keep Vim usable on older systems. - Many users start Vim from a shell very often. Startup time must be short. @@ -57,7 +55,8 @@ Keep Nvim small and fast. - Don't forget that some people use Vim over a slow connection. Minimize the communication overhead. - Vim is a component among other components. Don't turn it into a massive - application, but have it work well together with other programs. + application, but have it work well together with other programs + ("composability"). NVIM IS... MAINTAINABLE *design-maintain* @@ -250,13 +249,25 @@ vim.paste in runtime/lua/vim/_editor.lua like this: > LUA *dev-lua* - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or - pseudo-OOP designs. Plugin authors just want functions to call, they don't - want to learn a big, fancy inheritance hierarchy. Thus avoid specialized - objects; tables or values are usually better. + pseudo-OOP designs. Plugin authors just want functions to call, not a big, + fancy inheritance hierarchy. +- Avoid requiring or returning special objects in the Nvim stdlib. Plain + tables or values are easier to serialize, easier to construct from literals, + easier to inspect and print, and inherently compatible with all Lua plugins. + (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.) API *dev-api* +- Avoid "mutually exclusive" parameters--via constraints or limitations, if + necessary. For example nvim_create_autocmd() has mutually exclusive + "callback" and "command" args; but the "command" arg could be eliminated by + simply not supporting Vimscript function names, and treating a string + "callback" arg as an Ex command (which can call Vimscript functions). The + "buffer" arg could also be eliminated by treating a number "pattern" as + a buffer number. + + *dev-api-naming* Use this format to name new RPC |API| functions: nvim_{thing}_{action}_{arbitrary-qualifiers} diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 3cfc3429de..13b953ed60 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -423,9 +423,8 @@ Note that such expressions are only supported in places where a filename is expected as an argument to an Ex-command. *++opt* *[++opt]* -The [++opt] argument can be used to force the value of 'fileformat', -'fileencoding' or 'binary' to a value for one command, and to specify the -behavior for bad characters. The form is: > +The [++opt] argument can be used to set some options for one command, and to +specify the behavior for bad characters. The form is: > ++{optname} Or: > ++{optname}={value} @@ -436,13 +435,11 @@ Where {optname} is one of: *++ff* *++enc* *++bin* *++nobin* *++edit* bin or binary sets 'binary' nobin or nobinary resets 'binary' bad specifies behavior for bad characters - edit for |:read| only: keep option values as if editing - a file - p creates the parent directory (or directories) of - a filename if they do not exist + edit for |:read|: keeps options as if editing a file + p for |:write|: creates the file's parent directory -{value} cannot contain white space. It can be any valid value for these -options. Examples: > +{value} cannot contain whitespace. It can be any valid value for the options. +Examples: > :e ++ff=unix This edits the same file again with 'fileformat' set to "unix". > @@ -452,9 +449,24 @@ This writes the current buffer to "newfile" in latin1 format. The message given when writing a file will show "[converted]" when 'fileencoding' or the value specified with ++enc differs from 'encoding'. -There may be several ++opt arguments, separated by white space. They must all +There may be several ++opt arguments, separated by whitespace. They must all appear before any |+cmd| argument. + *++p* +The "++p" flag creates the parent directory of the file if it does not exist. +For example if you edit "foo/bar/file.txt", the ":write ++p" command creates +"foo/bar/" if necessary before writing the file. > + + :edit foo/bar/file.txt + :write ++p + +If you want :write (without "++p") to always create missing parent +directories, add this autocmd to your config: > + + " Auto-create parent directories (except for URIs "://"). + au BufWritePre,FileWritePre * if @% !~# '\(://\)' | call mkdir(expand(':p:h'), 'p') | endif +< + *++bad* The argument of "++bad=" specifies what happens with characters that can't be converted and illegal bytes. It can be one of three things: @@ -895,11 +907,13 @@ Note: When the 'write' option is off, you are not able to write any file. *E502* *E503* *E504* *E505* *E512* *E514* *E667* *E949* :w[rite] [++opt] Write the whole buffer to the current file. This is - the normal way to save changes to a file. It fails - when the 'readonly' option is set or when there is - another reason why the file can't be written. - For ++opt see |++opt|, but only ++bin, ++nobin, ++ff - and ++enc are effective. + the normal way to save changes to a file. Fails when + 'readonly' is set or when there is another reason why + the file can't be written, such as when the parent + directory doesn't exist (use |++p| to avoid that). + For ++opt see |++opt|, but only ++p, ++bin, ++nobin, + ++ff and ++enc are effective. + :w[rite]! [++opt] Like ":write", but forcefully write when 'readonly' is set or there is another reason why writing was diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index c989b67b96..61d540a3dd 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1708,13 +1708,13 @@ v:charconvert_to *v:cmdarg* *cmdarg-variable* v:cmdarg This variable is used for two purposes: - 1. The extra arguments given to a file read/write command. - Currently these are "++enc=" and "++ff=". This variable is - set before an autocommand event for a file read/write - command is triggered. There is a leading space to make it - possible to append this variable directly after the - read/write command. Note: The "+cmd" argument isn't - included here, because it will be executed anyway. + 1. The extra arguments ("++p", "++enc=", "++ff=") given to + a file read/write command. This is set before an + autocommand event for a file read/write command is + triggered. There is a leading space to make it possible to + append this variable directly after the read/write command. + Note: "+cmd" isn't included here, because it will be + executed anyway. 2. When printing a PostScript file with ":hardcopy" this is the argument for the ":hardcopy" command. This can be used in 'printexpr'. diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 37a0a8c076..89a6e89511 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -325,7 +325,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method }, } < - or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`: + or if using "nvim-lspconfig", you can use the {handlers} key of `setup()`: >lua require('lspconfig').rust_analyzer.setup { @@ -1340,9 +1340,7 @@ start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()* |vim.lsp.buf_attach_client()|. To opt-out of semantic highlighting with a server that supports it, you can delete the semanticTokensProvider table from the {server_capabilities} of your client in your |LspAttach| callback - or your configuration's `on_attach` callback. - - >lua + or your configuration's `on_attach` callback. >lua client.server_capabilities.semanticTokensProvider = nil < diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 4946779a7c..ef407922da 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -24,8 +24,8 @@ Transitioning from Vim *nvim-from-vim* 1. To start the transition, create your |init.vim| (user config) file: >vim - :call mkdir(stdpath('config'), 'p') :exe 'edit '.stdpath('config').'/init.vim' + :write ++p 2. Add these contents to the file: >vim diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index 8f2feb416b..5375d971f0 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -176,7 +176,7 @@ a |provider| which transparently uses shell commands to communicate with the system clipboard or any other clipboard "backend". To ALWAYS use the clipboard for ALL operations (instead of interacting with -the '+' and/or '*' registers explicitly): >vim +the "+" and/or "*" registers explicitly): >vim set clipboard+=unnamedplus See 'clipboard' for details and options. diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 6a2e74eaf5..5c1725a1f8 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -127,7 +127,7 @@ nvim_cmdwin: ============================================================================== 3. New Features *nvim-features* -MAJOR COMPONENTS ~ +MAJOR COMPONENTS API |API| Job control |job-control| @@ -145,7 +145,7 @@ Terminal emulator |terminal| Vimscript parser |nvim_parse_expression()| XDG base directories |xdg| -USER EXPERIENCE ~ +USER EXPERIENCE Working intuitively and consistently is a major goal of Nvim. @@ -176,7 +176,7 @@ Some features are built in that otherwise required external plugins: - Highlighting the yanked region, see |lua-highlight|. -ARCHITECTURE ~ +ARCHITECTURE External plugins run in separate processes. |remote-plugin| This improves stability and allows those plugins to work without blocking the editor. Even @@ -187,7 +187,7 @@ Platform and I/O facilities are built upon libuv. Nvim benefits from libuv features and bug fixes, and other projects benefit from improvements to libuv by Nvim developers. -FEATURES ~ +FEATURES Command-line highlighting: The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted @@ -206,6 +206,7 @@ Commands: |:match| can be invoked before highlight group is defined |:source| works with Lua User commands can support |:command-preview| to show results as you type + |:write| with "++p" flag creates parent directories. Events: |RecordingEnter| @@ -226,6 +227,7 @@ Functions: |stdpath()| |system()|, |systemlist()| can run {cmd} directly (without 'shell') |matchadd()| can be called before highlight group is defined + |writefile()| with "p" flag creates parent directories. Highlight groups: |highlight-blend| controls blend level for a highlight group @@ -277,7 +279,20 @@ Variables: |v:windowid| is always available (for use by external UIs) ============================================================================== -4. Changed features *nvim-features-changed* +4. Upstreamed features *nvim-upstreamed* + +These Nvim features were later integrated into Vim. + +- 'fillchars' flags: "eob" +- 'wildoptions' flags: "pum" enables popupmenu for wildmode completion +- || +- |WinClosed| +- |WinScrolled| +- |:sign-define| "numhl" argument +- |:source| works with anonymous (no file) scripts + +============================================================================== +5. Changed features *nvim-features-changed* Nvim always builds with all features, in contrast to Vim which may have certain features removed/added at compile-time. |feature-compile| @@ -499,7 +514,7 @@ Working directory (Vim implemented some of these later than Nvim): working directory. Use `getcwd(-1, -1)` to get the global working directory. ============================================================================== -5. Missing legacy features *nvim-features-missing* +6. Missing legacy features *nvim-features-missing* Some legacy Vim features are not yet implemented: @@ -512,7 +527,7 @@ Some legacy Vim features are not yet implemented: *:gvim* ============================================================================== -6. Removed features *nvim-features-removed* +7. Removed features *nvim-features-removed* These Vim features were intentionally removed from Nvim. diff --git a/runtime/lua/vim/lsp/semantic_tokens.lua b/runtime/lua/vim/lsp/semantic_tokens.lua index 83b414bf87..11e62ee793 100644 --- a/runtime/lua/vim/lsp/semantic_tokens.lua +++ b/runtime/lua/vim/lsp/semantic_tokens.lua @@ -495,7 +495,6 @@ local M = {} --- delete the semanticTokensProvider table from the {server_capabilities} of --- your client in your |LspAttach| callback or your configuration's --- `on_attach` callback. ---- --- 
lua
 ---   client.server_capabilities.semanticTokensProvider = nil
 ---
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 3a0ed5ffc5..78fb917764 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -296,12 +296,11 @@ local function ignore_invalid(s) ) end -local function ignore_parse_error(s, fname) - local helpfile = vim.fs.basename(fname) - return (helpfile == 'pi_netrw.txt' +local function ignore_parse_error(s) + return ( -- Ignore parse errors for unclosed tag. -- This is common in vimdocs and is treated as plaintext by :help. - or s:find("^[`'|*]") + s:find("^[`'|*]") ) end @@ -370,7 +369,7 @@ local function visit_validate(root, level, lang_tree, opt, stats) end if node_name == 'ERROR' then - if ignore_parse_error(text, opt.fname) then + if ignore_parse_error(text) then return end -- Store the raw text to give context to the error report. @@ -582,7 +581,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) end return s elseif node_name == 'ERROR' then - if ignore_parse_error(trimmed, opt.fname) then + if ignore_parse_error(trimmed) then return text end diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index db84ecb5d8..ada042e654 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -361,41 +361,20 @@ cleanup: return autocmd_list; } -/// Create an |autocommand| +/// Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript +/// function _name_ string) or `command` (Ex command string). /// -/// The API allows for two (mutually exclusive) types of actions to be executed when the autocommand -/// triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands). -/// -/// Example using callback: +/// Example using Lua callback: /// 
lua
-///     -- Lua function
-///     local myluafun = function() print("This buffer enters") end
-///
-///     -- Vimscript function name (as a string)
-///     local myvimfun = "g:MyVimFunction"
-///
 ///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
 ///       pattern = {"*.c", "*.h"},
-///       callback = myluafun,  -- Or myvimfun
+///       callback = function(ev)
+///         print(string.format('event fired: %s', vim.inspect(ev)))
+///       end
 ///     })
 ///
/// -/// Lua functions receive a table with information about the autocmd event as an argument. To use -/// a function which itself accepts another (optional) parameter, wrap the function -/// in a lambda: -/// 
lua
-///     -- Lua function with an optional parameter.
-///     -- The autocmd callback would pass a table as argument but this
-///     -- function expects number|nil
-///     local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
-///
-///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///       pattern = {"*.c", "*.h"},
-///       callback = function() myluafun() end,
-///     })
-///
-/// -/// Example using command: +/// Example using an Ex command as the handler: /// 
lua
 ///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
 ///       pattern = {"*.c", "*.h"},
@@ -403,46 +382,28 @@ cleanup:
 ///     })
 ///
/// -/// Example values for pattern: -/// 
lua
-///   pattern = "*.py"
-///   pattern = { "*.py", "*.pyi" }
-///
-/// -/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment -/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. -/// Instead, |expand()| such variables explicitly: +/// Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like "$HOME" +/// and "~" must be expanded explicitly: /// 
lua
 ///   pattern = vim.fn.expand("~") .. "/some/path/*.py"
 ///
/// -/// Example values for event: -/// 
lua
-///   event = "BufWritePre"
-///   event = {"CursorHold", "BufWritePre", "BufWritePost"}
-///
-/// -/// @param event (string|array) The event or events to register this autocommand -/// @param opts Dictionary of autocommand options: -/// - group (string|integer) optional: the autocommand group name or -/// id to match against. -/// - pattern (string|array) optional: pattern or patterns to match literally -/// against |autocmd-pattern|. -/// - buffer (integer) optional: buffer number for buffer local autocommands +/// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`). +/// @param opts Options dict: +/// - group (string|integer) optional: autocommand group name or id to match against. +/// - pattern (string|array) optional: pattern(s) to match literally |autocmd-pattern|. +/// - buffer (integer) optional: buffer number for buffer-local autocommands /// |autocmd-buflocal|. Cannot be used with {pattern}. -/// - desc (string) optional: description of the autocommand. -/// - callback (function|string) optional: if a string, the name of a Vimscript function -/// to call when this autocommand is triggered. Otherwise, a Lua function which is -/// called when this autocommand is triggered. Cannot be used with {command}. Lua -/// callbacks can return true to delete the autocommand; in addition, they accept a -/// single table argument with the following keys: -/// - id: (number) the autocommand id -/// - event: (string) the name of the event that triggered the autocommand -/// |autocmd-events| -/// - group: (number|nil) the autocommand group id, if it exists -/// - match: (string) the expanded value of || -/// - buf: (number) the expanded value of || -/// - file: (string) the expanded value of || +/// - desc (string) optional: description (for documentation and troubleshooting). +/// - callback (function|string) optional: Lua function (or Vimscript function name, if +/// string) called when the event(s) is triggered. Lua callback can return true to +/// delete the autocommand, and receives a table argument with these keys: +/// - id: (number) autocommand id +/// - event: (string) name of the triggered event |autocmd-events| +/// - group: (number|nil) autocommand group id, if any +/// - match: (string) expanded value of || +/// - buf: (number) expanded value of || +/// - file: (string) expanded value of || /// - data: (any) arbitrary data passed to |nvim_exec_autocmds()| /// - command (string) optional: Vim command to execute on event. Cannot be used with /// {callback} @@ -451,7 +412,7 @@ cleanup: /// - nested (boolean) optional: defaults to false. Run nested /// autocommands |autocmd-nested|. /// -/// @return Integer id of the created autocommand. +/// @return Autocommand id (number) /// @see |autocommand| /// @see |nvim_del_autocmd()| Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autocmd) *opts, @@ -472,8 +433,7 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc } if (opts->callback.type != kObjectTypeNil && opts->command.type != kObjectTypeNil) { - api_set_error(err, kErrorTypeValidation, - "cannot pass both: 'callback' and 'command' for the same autocmd"); + api_set_error(err, kErrorTypeValidation, "specify either 'callback' or 'command', not both"); goto cleanup; } else if (opts->callback.type != kObjectTypeNil) { // TODO(tjdevries): It's possible we could accept callable tables, diff --git a/test/functional/api/autocmd_spec.lua b/test/functional/api/autocmd_spec.lua index a923f5df0e..7fb52b097b 100644 --- a/test/functional/api/autocmd_spec.lua +++ b/test/functional/api/autocmd_spec.lua @@ -14,14 +14,14 @@ before_each(clear) describe('autocmd api', function() describe('nvim_create_autocmd', function() - it('does not allow "command" and "callback" in the same autocmd', function() - local ok, _ = pcall(meths.create_autocmd, "BufReadPost", { + it('"command" and "callback" are mutually exclusive', function() + local rv = pcall_err(meths.create_autocmd, "BufReadPost", { pattern = "*.py,*.pyi", command = "echo 'Should Have Errored", - callback = "not allowed", + callback = "NotAllowed", }) - eq(false, ok) + eq("specify either 'callback' or 'command', not both", rv) end) it('doesnt leak when you use ++once', function() @@ -60,13 +60,13 @@ describe('autocmd api', function() end) it('does not allow passing buffer and patterns', function() - local ok = pcall(meths.create_autocmd, "Filetype", { + local rv = pcall_err(meths.create_autocmd, "Filetype", { command = "let g:called = g:called + 1", buffer = 0, pattern = "*.py", }) - eq(false, ok) + eq("cannot pass both: 'pattern' and 'buffer' for the same autocmd", rv) end) it('does not allow passing invalid buffers', function()