feat(lua): vim.keycode (#22960)

Using nvim_replace_termcodes is too verbose, add vim.keycode for
translating keycodes.

Co-authored-by: ii14 <ii14@users.noreply.github.com>

3 files changed, 32 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 8e68e9a792..c1c00df28e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1404,6 +1404,23 @@ inspect({object}, {options})                                   *vim.inspect()*
       • https://github.com/kikito/inspect.lua
       • https://github.com/mpeterv/vinspect
 
+keycode({str})                                                 *vim.keycode()*
+    Translate keycodes.
+
+    Example: >lua
+      local k = vim.keycode
+      vim.g.mapleader = k'<bs>'
+<
+
+    Parameters: ~
+      • {str}  string String to be converted.
+
+    Return: ~
+        string
+
+    See also: ~
+      • |nvim_replace_termcodes()|
+
 lua_omnifunc({find_start}, {_})                           *vim.lua_omnifunc()*
     Omnifunc for completing lua values from from the runtime lua interpreter,
     similar to the builtin completion for the `:lua` command.
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 3f07dd2e66..2a776ea30a 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -37,6 +37,7 @@ The following new APIs or features were added.
 
 • |vim.iter()| provides a generic iterator interface for tables and Lua
 iterators |luaref-in|.
+• Added |vim.keycode()| for translating keycodes in a string.
 
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index c922ec93db..20e813d77c 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -829,6 +829,20 @@ function vim.print(...)
   return ...
 end
 
+--- Translate keycodes.
+---
+--- Example:
+--- <pre>lua
+---   local k = vim.keycode
+---   vim.g.mapleader = k'<bs>'
+--- </pre>
+--- @param str string String to be converted.
+--- @return string
+--- @see |nvim_replace_termcodes()|
+function vim.keycode(str)
+  return vim.api.nvim_replace_termcodes(str, true, true, true)
+end
+
 function vim._cs_remote(rcid, server_addr, connect_error, args)
   local function connection_failure_errmsg(consequence)
     local explanation