diff options
| -rw-r--r-- | runtime/doc/deprecated.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 15 | ||||
| -rw-r--r-- | runtime/lua/vim/_editor.lua | 41 | ||||
| -rw-r--r-- | test/functional/lua/vim_spec.lua | 16 |
4 files changed, 47 insertions, 27 deletions
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index fe1d6f1645..74c50f00a2 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -128,7 +128,7 @@ TREESITTER FUNCTIONS and |TSNode:type()| instead. LUA -- *vim.register_keystroke_callback()* Use |vim.on_key()| instead. +- vim.register_keystroke_callback() Use |vim.on_key()| instead. - *vim.pretty_print()* Use |vim.print()| instead. NORMAL COMMANDS diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 68f63f4fb8..611f2e0d32 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1386,17 +1386,20 @@ defer_fn({fn}, {timeout}) *vim.defer_fn()* *vim.deprecate()* deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) - Display a deprecation notification to the user. + Shows a deprecation message to the user. Parameters: ~ - • {name} string Deprecated function. - • {alternative} (string|nil) Preferred alternative function. - • {version} string Version in which the deprecated function will be + • {name} string Deprecated feature (function, API, etc.). + • {alternative} (string|nil) Suggested alternative feature. + • {version} string Version when the deprecated function will be removed. - • {plugin} string|nil Plugin name that the function will be - removed from. Defaults to "Nvim". + • {plugin} string|nil Name of the plugin that owns the deprecated + feature. Defaults to "Nvim". • {backtrace} boolean|nil Prints backtrace. Defaults to true. + Return: ~ + Deprecated message, or nil if no message was shown. + inspect({object}, {options}) *vim.inspect()* Gets a human-readable representation of the given object. diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index 5445c4e492..f2875e5646 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -518,11 +518,6 @@ do end end ----@private -function vim.register_keystroke_callback() - error('vim.register_keystroke_callback is deprecated, instead use: vim.on_key') -end - local on_key_cbs = {} --- Adds Lua function {fn} with namespace id {ns_id} as a listener to every, @@ -882,27 +877,33 @@ function vim._cs_remote(rcid, server_addr, connect_error, args) } end ---- Display a deprecation notification to the user. +--- Shows a deprecation message to the user. --- ----@param name string Deprecated function. ----@param alternative string|nil Preferred alternative function. ----@param version string Version in which the deprecated function will ---- be removed. ----@param plugin string|nil Plugin name that the function will be removed ---- from. Defaults to "Nvim". +---@param name string Deprecated feature (function, API, etc.). +---@param alternative string|nil Suggested alternative feature. +---@param version string Version when the deprecated function will be removed. +---@param plugin string|nil Name of the plugin that owns the deprecated feature. +--- Defaults to "Nvim". ---@param backtrace boolean|nil Prints backtrace. Defaults to true. +--- +---@returns Deprecated message, or nil if no message was shown. function vim.deprecate(name, alternative, version, plugin, backtrace) - local message = name .. ' is deprecated' + local msg = ('%s is deprecated'):format(name) plugin = plugin or 'Nvim' - message = alternative and (message .. ', use ' .. alternative .. ' instead.') or message - message = message - .. ' See :h deprecated\nThis function will be removed in ' - .. plugin - .. ' version ' - .. version - if vim.notify_once(message, vim.log.levels.WARN) and backtrace ~= false then + msg = alternative and ('%s, use %s instead.'):format(msg, alternative) or msg + msg = ('%s%s\nThis feature will be removed in %s version %s'):format( + msg, + (plugin == 'Nvim' and ' :help deprecated' or ''), + plugin, + version + ) + local displayed = vim.notify_once(msg, vim.log.levels.WARN) + if displayed and backtrace ~= false then vim.notify(debug.traceback('', 2):sub(2), vim.log.levels.WARN) end + if displayed then + return msg + end end --- Create builtin mappings (incl. menus). diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua index 470102df5e..0483ec46f0 100644 --- a/test/functional/lua/vim_spec.lua +++ b/test/functional/lua/vim_spec.lua @@ -127,6 +127,22 @@ describe('lua stdlib', function() eq(1, funcs.luaeval('vim.stricmp("\\0C\\0", "\\0B\\0")')) end) + it('vim.deprecate', function() + -- vim.deprecate(name, alternative, version, plugin, backtrace) + eq(dedent[[ + foo.bar() is deprecated, use zub.wooo{ok=yay} instead. :help deprecated + This feature will be removed in Nvim version 2.17]], + exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '2.17')) + -- Same message, skipped. + eq(vim.NIL, + exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '2.17')) + -- When `plugin` is specified, don't show ":help deprecated". #22235 + eq(dedent[[ + foo.bar() is deprecated, use zub.wooo{ok=yay} instead. + This feature will be removed in my-plugin.nvim version 0.3.0]], + exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', '0.3.0', 'my-plugin.nvim', false)) + end) + it('vim.startswith', function() eq(true, funcs.luaeval('vim.startswith("123", "1")')) eq(true, funcs.luaeval('vim.startswith("123", "")')) |