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

@@ -1315,7 +1315,7 @@ nvim_paste({data}, {crlf}, {phase})                             *nvim_paste()*
             line2
             line3
           ]], false, -1)
-        end, { buf = true })
+        end, { buf = 0 })
 <
 
     Attributes: ~

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', '<Leader>pl1', require('plugin').action, { buf = true })
+    vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { buf = 0 })
     -- set mapping for the buffer number 4
     vim.keymap.set('n', '<Leader>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', '<Leader>ex1')
-    vim.keymap.del({'n', 'c'}, '<Leader>ex2', { buf = true })
+    vim.keymap.del({'n', 'c'}, '<Leader>ex2', { buf = 0 })
 <
 See also:
 • `vim.api.`|nvim_get_keymap()|:     return all global mapping

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 "<leader>x" to multiple modes for the current buffer:
-        vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buf = true })
+        vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buf = 0 })
         -- Map <Tab> to an expression (|:map-<expr>|):
         vim.keymap.set('i', '<Tab>', function()
           return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
@@ -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}.
 

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

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).

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 "<leader>x" to multiple modes for the current buffer:
---- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buf = true })
+--- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buf = 0 })
 --- -- Map <Tab> to an expression (|:map-<expr>|):
 --- vim.keymap.set('i', '<Tab>', function()
 ---   return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
@@ -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

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).

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