From 9a5641b4b57082d3de3574a2776b55dcd444143c Mon Sep 17 00:00:00 2001 From: skewb1k Date: Mon, 23 Mar 2026 12:00:53 +0000 Subject: [PATCH] fix(lua): drop support for boolean `buf` in `vim.keymap` #38432 Problem: `vim.keymap.*.Opts.buf` allows `boolean` aliases for more widely used `integer?` values, `true` -> `0` and `false` -> `nil`. This conversion is unnecessary and can be handled at call sites. Solution: As a follow-up to deprecating the `buffer` option, drop support for boolean values for the new `buf` option. The deprecated `buffer` continues to support booleans for backward compatibility. --- runtime/doc/api.txt | 2 +- runtime/doc/lua-guide.txt | 4 ++-- runtime/doc/lua.txt | 10 +++++----- runtime/ftplugin/help.lua | 2 +- runtime/lua/vim/_meta/api.lua | 2 +- runtime/lua/vim/keymap.lua | 17 +++++++---------- src/nvim/api/vim.c | 2 +- test/functional/lua/vim_spec.lua | 10 +++++----- 8 files changed, 23 insertions(+), 26 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c8df112ac7..0423eafa40 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1315,7 +1315,7 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* line2 line3 ]], false, -1) - end, { buf = true }) + end, { buf = 0 }) < Attributes: ~ diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index 7abdb3f2dc..994e1f292c 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -429,7 +429,7 @@ useful options: • `buf`: If given, only set the mapping for the buffer with the specified number; `0` or `true` means the current buffer. >lua -- set mapping for the current buffer - vim.keymap.set('n', 'pl1', require('plugin').action, { buf = true }) + vim.keymap.set('n', 'pl1', require('plugin').action, { buf = 0 }) -- set mapping for the buffer number 4 vim.keymap.set('n', 'pl1', require('plugin').action, { buf = 4 }) < @@ -467,7 +467,7 @@ Removing mappings *lua-guide-mappings-del* A specific mapping can be removed with |vim.keymap.del()|: >lua vim.keymap.del('n', 'ex1') - vim.keymap.del({'n', 'c'}, 'ex2', { buf = true }) + vim.keymap.del({'n', 'c'}, 'ex2', { buf = 0 }) < See also: • `vim.api.`|nvim_get_keymap()|: return all global mapping diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 5a05ef17d4..5e03ba728d 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -3605,8 +3605,8 @@ vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* • {modes} (`string|string[]`) • {lhs} (`string`) • {opts} (`table?`) A table with the following fields: - • {buf}? (`integer|boolean`) Remove a mapping from the given - buffer. When `0` or `true`, use the current buffer. + • {buf}? (`integer`) Remove a mapping from the given buffer. + `0` for current. See also: ~ • |vim.keymap.set()| @@ -3618,7 +3618,7 @@ vim.keymap.set({modes}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* -- Map "x" to a Lua function: vim.keymap.set('n', 'x', function() print('real lua function') end) -- Map "x" to multiple modes for the current buffer: - vim.keymap.set({'n', 'v'}, 'x', vim.lsp.buf.references, { buf = true }) + vim.keymap.set({'n', 'v'}, 'x', vim.lsp.buf.references, { buf = 0 }) -- Map to an expression (|:map-|): vim.keymap.set('i', '', function() return vim.fn.pumvisible() == 1 and '' or '' @@ -3652,8 +3652,8 @@ vim.keymap.set({modes}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* below). Also accepts: - • {buf}? (`integer|boolean`) Creates buffer-local mapping, - `0` or `true` for current buffer. + • {buf}? (`integer`) Creates buffer-local mapping, `0` for + current buffer. • {remap}? (`boolean`, default: `false`) Make the mapping recursive. Inverse of {noremap}. diff --git a/runtime/ftplugin/help.lua b/runtime/ftplugin/help.lua index eb807b473b..d5384ecd51 100644 --- a/runtime/ftplugin/help.lua +++ b/runtime/ftplugin/help.lua @@ -111,7 +111,7 @@ local function runnables() elseif code_block.lang == 'vim' then vim.cmd(code_block.code) end - end, { buf = true }) + end, { buf = 0 }) end -- Retry once if the buffer has changed during the iteration of the code diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index dc5bf098b7..2eec5633bc 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -2018,7 +2018,7 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- line2 --- line3 --- ]], false, -1) ---- end, { buf = true }) +--- end, { buf = 0 }) --- ``` --- --- @param data string Multiline input. Lines break at LF ("\n"). May be binary (containing NUL bytes). diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index 94e1df0f31..7680196d5d 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -9,8 +9,8 @@ local keymap = {} --- @class vim.keymap.set.Opts : vim.api.keyset.keymap --- @inlinedoc --- ---- Creates buffer-local mapping, `0` or `true` for current buffer. ---- @field buf? integer|boolean +--- Creates buffer-local mapping, `0` for current buffer. +--- @field buf? integer --- --- Make the mapping recursive. Inverse of {noremap}. --- (Default: `false`) @@ -24,7 +24,7 @@ local keymap = {} --- -- Map "x" to a Lua function: --- vim.keymap.set('n', 'x', function() print('real lua function') end) --- -- Map "x" to multiple modes for the current buffer: ---- vim.keymap.set({'n', 'v'}, 'x', vim.lsp.buf.references, { buf = true }) +--- vim.keymap.set({'n', 'v'}, 'x', vim.lsp.buf.references, { buf = 0 }) --- -- Map to an expression (|:map-|): --- vim.keymap.set('i', '', function() --- return vim.fn.pumvisible() == 1 and '' or '' @@ -89,12 +89,11 @@ function keymap.set(modes, lhs, rhs, opts) if opts.buffer ~= nil then -- TODO(skewb1k): soft-deprecate `buffer` option in 0.13, remove in 0.15. assert(buf == nil, "Conflict: 'buf' not allowed with 'buffer'") - buf = opts.buffer + buf = opts.buffer == true and 0 or opts.buffer --[[@as integer?]] opts.buffer = nil end if buf then - buf = buf == true and 0 or buf for _, m in ipairs(modes) do vim.api.nvim_buf_set_keymap(buf, m, lhs, rhs, opts) end @@ -108,9 +107,8 @@ end --- @class vim.keymap.del.Opts --- @inlinedoc --- ---- Remove a mapping from the given buffer. ---- When `0` or `true`, use the current buffer. ---- @field buf? integer|boolean +--- Remove a mapping from the given buffer. `0` for current. +--- @field buf? integer --- Remove an existing mapping. --- Examples: @@ -139,11 +137,10 @@ function keymap.del(modes, lhs, opts) if opts.buffer ~= nil then -- TODO(skewb1k): soft-deprecate `buffer` option in 0.13, remove in 0.15. assert(opts.buf == nil, "Conflict: 'buf' not allowed with 'buffer'") - buf = opts.buffer + buf = opts.buffer == true and 0 or opts.buffer --[[@as integer?]] end if buf then - buf = buf == true and 0 or buf for _, mode in ipairs(modes) do vim.api.nvim_buf_del_keymap(buf, mode, lhs) end diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 3b7f90cc6d..2975fec2e7 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1320,7 +1320,7 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err) /// line2 /// line3 /// ]], false, -1) -/// end, { buf = true }) +/// end, { buf = 0 }) /// ``` /// /// @param data Multiline input. Lines break at LF ("\n"). May be binary (containing NUL bytes). diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua index ac40a95c75..e80fb777f3 100644 --- a/test/functional/lua/vim_spec.lua +++ b/test/functional/lua/vim_spec.lua @@ -3178,7 +3178,7 @@ describe('vim.keymap', function() 0, exec_lua [[ GlobalCount = 0 - vim.keymap.set('n', 'asdf', function() GlobalCount = GlobalCount + 1 end, {buf=true}) + vim.keymap.set('n', 'asdf', function() GlobalCount = GlobalCount + 1 end, {buf=0}) return GlobalCount ]] ) @@ -3188,7 +3188,7 @@ describe('vim.keymap', function() eq(1, exec_lua [[return GlobalCount]]) exec_lua [[ - vim.keymap.del('n', 'asdf', {buf=true}) + vim.keymap.del('n', 'asdf', {buf=0}) ]] feed('asdf\n') @@ -3199,15 +3199,15 @@ describe('vim.keymap', function() it('does not mutate the opts parameter', function() eq( - true, + 0, exec_lua [[ - opts = {buf=true} + opts = {buf=0} vim.keymap.set('n', 'asdf', function() end, opts) return opts.buf ]] ) eq( - true, + 0, exec_lua [[ vim.keymap.del('n', 'asdf', opts) return opts.buf