feat(lua): vim.keycode() gets structured parse result #38636

Problems:
1. Can't get individual parts of a key-chord separately: modifiers, key.
2. Can't separate a key-combo into individual key-chords.

Solution:
Enhance `vim.keycode()` to optionally return a structured parse result
as a list of key-chords:
- `key_raw` the key-chord (problem 2)
- `mod` the modifiers of `key_raw` (problem 1)
- `key_orig` the key part of the key-chord, only here if differing from `key`
  (this doesn't solve any of the above mentioned problems, but it may provide
  useful and it's (in terms of code) free)
- `key` a normalized version of `key_orig` (solving problem 1), example(the
  first is `key_orig` and second is `key`): `lt` and `<`, `Bar` and `|` (in
  `<C-Bar>`)

test/functional/editor/keycode_spec.lua

@@ -0,0 +1,63 @@
+local t = require('test.testutil')
+local n = require('test.functional.testnvim')()
+
+local eq = t.eq
+local exec_lua = n.exec_lua
+local clear = n.clear
+
+describe('vim.keycode() detailed info', function()
+  before_each(clear)
+
+  local function parse(key, simplify)
+    local parsed = exec_lua([[return select(2,vim.keycode(...,true))]], key)
+    return vim.tbl_map(function(tbl)
+      if simplify == 1 then
+        return { tbl.mod, tbl.key }
+      elseif simplify == 2 then
+        return { tbl.mod, tbl.key, tbl.key_raw }
+      end
+      return tbl
+    end, parsed)
+  end
+
+  it('works', function()
+    eq({ { mod = { 'M' }, key = 'f', key_raw = '<M-f>' } }, parse('<A-f>'))
+    eq({ { { 'M' }, 'Home' } }, parse('<A-Home>', 1))
+    eq({ { { 'M' }, 'f' }, { {}, 'b' }, { {}, 'c' } }, parse('<A-f>b<char-99>', 1))
+
+    eq({ { { 'M' }, '>' } }, parse('<A->>', 1))
+    eq({ { { 'M' }, 't_>>' } }, parse('<A-t_>>>', 1))
+  end)
+
+  it('normalizes', function()
+    -- stylua: ignore start
+    eq({ { {},      '\\',   '<Bslash>'   } }, parse('\\', 2))
+    eq({ { { 'M' }, '\\',   '<M-Bslash>' } }, parse('<A-\\>', 2))
+    eq({ { { 'C' }, '\\',   '<C-\\>'     } }, parse('<C-\\>', 2))
+    eq({ { {},      '|',    '<Bar>'      } }, parse('|', 2))
+    eq({ { { 'M' }, '|',    '<M-Bar>'    } }, parse('<A-|>', 2))
+    eq({ { { 'C' }, '|',    '<C-Bar>'    } }, parse('<C-|>', 2))
+    eq({ { {},      '\127', '\127'       } }, parse('\127', 2))
+    eq({ { { 'M' }, '\127', '<M-^?>'     } }, parse('<A-\127>', 2))
+    eq({ { { 'C' }, '\127', '<C-^?>'     } }, parse('<C-\127>', 2))
+
+    eq({ { {}, '<',    '<lt>'    } }, parse('<', 2))
+    eq({ { {}, '\t',   '<Tab>'   } }, parse('\t', 2))
+    eq({ { {}, '\r',   '<CR>'    } }, parse('\r', 2))
+    eq({ { {}, '\n',   '<NL>'    } }, parse('\n', 2))
+    eq({ { {}, '\27',  '<Esc>'   } }, parse('\27', 2))
+    eq({ { {}, ' ',    '<Space>' } }, parse(' ', 2))
+
+    eq({ { { 'S' }, 'a', 'A'     } }, parse('A', 2))
+    eq({ { { 'C' }, 'a', '<C-A>' } }, parse('<C-a>', 2))
+    -- stylua: ignore end
+
+    eq({ { mod = {}, key = '<', key_raw = '<lt>', key_orig = 'lt' } }, parse('<'))
+  end)
+
+  it('handles utf8-chars', function()
+    eq({ { {}, 'ö' }, { { 'M' }, 'ó' }, { {}, 'ú' }, { {}, 'ü' } }, parse('ö<A-ó>úü', 1))
+    eq({ { {}, 'a' }, { {}, '\226\129\129' }, { {}, 'b' } }, parse('a\226\129\129b', 1))
+    eq({ { {}, 'a' }, { {}, '\242\129\129\129' }, { {}, 'b' } }, parse('a\242\129\129\129b', 1))
+  end)
+end)