feat: add vim.text module (#26069)

6 files changed, 84 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index db240e8b75..596b58d4ff 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -3752,4 +3752,26 @@ vim.snippet.jumpable({direction})                     *vim.snippet.jumpable()*
     Return: ~
         (boolean)
 
+
+==============================================================================
+Lua module: vim.text                                                *vim.text*
+
+vim.text.hexdecode({enc})                               *vim.text.hexdecode()*
+    Hex decode a string.
+
+    Parameters: ~
+      • {enc}  (string) String to decode
+
+    Return: ~
+        (string) Decoded string
+
+vim.text.hexencode({str})                               *vim.text.hexencode()*
+    Hex encode a string.
+
+    Parameters: ~
+      • {str}  (string) String to encode
+
+    Return: ~
+        (string) Hex encoded string
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index ae97772b66..98848f548f 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -214,6 +214,9 @@ The following new APIs and features were added.
 • The 'termsync' option asks the terminal emulator to buffer screen updates
   until the redraw cycle is complete. Requires support from the terminal.
 
+• Added |vim.text.hexencode()| and |vim.text.hexdecode()| to convert strings
+  to and from byte representations.
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
 
diff --git a/runtime/lua/vim/_init_packages.lua b/runtime/lua/vim/_init_packages.lua
index 8750afba34..4a961970cc 100644
--- a/runtime/lua/vim/_init_packages.lua
+++ b/runtime/lua/vim/_init_packages.lua
@@ -57,6 +57,7 @@ vim._submodules = {
   fs = true,
   iter = true,
   re = true,
+  text = true,
 }
 
 -- These are for loading runtime modules in the vim namespace lazily.
diff --git a/runtime/lua/vim/text.lua b/runtime/lua/vim/text.lua
new file mode 100644
index 0000000000..cfb0f9b821
--- /dev/null
+++ b/runtime/lua/vim/text.lua
@@ -0,0 +1,32 @@
+--- Text processing functions.
+
+local M = {}
+
+--- Hex encode a string.
+---
+--- @param str string String to encode
+--- @return string Hex encoded string
+function M.hexencode(str)
+  local bytes = { str:byte(1, #str) }
+  local enc = {} ---@type string[]
+  for i = 1, #bytes do
+    enc[i] = string.format('%02X', bytes[i])
+  end
+  return table.concat(enc)
+end
+
+--- Hex decode a string.
+---
+--- @param enc string String to decode
+--- @return string Decoded string
+function M.hexdecode(enc)
+  assert(#enc % 2 == 0, 'string must have an even number of hex characters')
+  local str = {} ---@type string[]
+  for i = 1, #enc, 2 do
+    local n = assert(tonumber(enc:sub(i, i + 1), 16))
+    str[#str + 1] = string.char(n)
+  end
+  return table.concat(str)
+end
+
+return M
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 3566d52f6e..925e6f98e6 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -167,6 +167,7 @@ CONFIG = {
             'version.lua',
             'iter.lua',
             'snippet.lua',
+            'text.lua',
         ],
         'files': [
             'runtime/lua/vim/iter.lua',
@@ -184,6 +185,7 @@ CONFIG = {
             'runtime/lua/vim/version.lua',
             'runtime/lua/vim/_inspector.lua',
             'runtime/lua/vim/snippet.lua',
+            'runtime/lua/vim/text.lua',
             'runtime/lua/vim/_meta/builtin.lua',
             'runtime/lua/vim/_meta/diff.lua',
             'runtime/lua/vim/_meta/mpack.lua',
@@ -247,6 +249,7 @@ CONFIG = {
             'regex': 'vim.regex',
             'spell': 'vim.spell',
             'snippet': 'vim.snippet',
+            'text': 'vim.text',
         },
         'append_only': [
             'shared.lua',
diff --git a/test/functional/lua/text_spec.lua b/test/functional/lua/text_spec.lua
new file mode 100644
index 0000000000..68206557c3
--- /dev/null
+++ b/test/functional/lua/text_spec.lua
@@ -0,0 +1,23 @@
+local helpers = require('test.functional.helpers')(after_each)
+local clear = helpers.clear
+local eq = helpers.eq
+
+describe('vim.text', function()
+  before_each(clear)
+
+  describe('hexencode() and hexdecode()', function()
+    it('works', function()
+      local cases = {
+        { 'Hello world!', '48656C6C6F20776F726C6421' },
+        { '😂', 'F09F9882' },
+      }
+
+      for _, v in ipairs(cases) do
+        local input, output = unpack(v)
+        eq(output, vim.text.hexencode(input))
+        eq(input, vim.text.hexdecode(output))
+      end
+    end)
+  end)
+end)
+