|
+- |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()
-[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 |