refactor: use kwargs parameter in vim.split

3 files changed, 39 insertions, 28 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 208a94e377..4ceb123ffc 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1373,23 +1373,25 @@ pesc({s})                                                         *vim.pesc()*
                 See also: ~
                     https://github.com/rxi/lume
 
-split({s}, {sep}, {plain}, {trimempty})                          *vim.split()*
+split({s}, {sep}, {kwargs})                                      *vim.split()*
                 Splits a string at each instance of a separator.
 
                 Examples: >
-                 split(":aa::b:", ":")     --> {'','aa','','b',''}
-                 split("axaby", "ab?")     --> {'','x','y'}
-                 split("x*yz*o", "*", true)  --> {'x','yz','o'}
-                 split("|x|y|z|", "|", true, true) --> {'x', 'y', 'z'}
+
+                  split(":aa::b:", ":")     --> {'','aa','','b',''}
+                  split("axaby", "ab?")     --> {'','x','y'}
+                  split("x*yz*o", "*", {plain=true})  --> {'x','yz','o'}
+                  split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 <
 
                 Parameters: ~
-                    {s}          String to split
-                    {sep}        Separator string or pattern
-                    {plain}      If `true` use `sep` literally (passed to
-                                 String.find)
-                    {trimempty}  If `true` remove empty items from the front
-                                 and back of the list
+                    {s}       String to split
+                    {sep}     Separator string or pattern
+                    {kwargs}  Keyword arguments:
+                              • plain: (boolean) If `true` use `sep` literally
+                                (passed to string.find)
+                              • trimempty: (boolean) If `true` remove empty
+                                items from the front and back of the list
 
                 Return: ~
                     List-like table of the split components.
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index e18dec9a45..b57b7ad4ad 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -98,20 +98,32 @@ end
 --- <pre>
 ---  split(":aa::b:", ":")     --> {'','aa','','b',''}
 ---  split("axaby", "ab?")     --> {'','x','y'}
----  split("x*yz*o", "*", true)  --> {'x','yz','o'}
----  split("|x|y|z|", "|", true, true) --> {'x', 'y', 'z'}
+---  split("x*yz*o", "*", {plain=true})  --> {'x','yz','o'}
+---  split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 --- </pre>
 ---
 ---@see |vim.gsplit()|
 ---
 ---@param s String to split
 ---@param sep Separator string or pattern
----@param plain If `true` use `sep` literally (passed to String.find)
----@param trimempty If `true` remove empty items from the front and back of the list
+---@param kwargs Keyword arguments:
+---       - plain: (boolean) If `true` use `sep` literally (passed to string.find)
+---       - trimempty: (boolean) If `true` remove empty items from the front
+---         and back of the list
 ---@returns List-like table of the split components.
-function vim.split(s, sep, plain, trimempty)
-  -- Only need to validate trimempty since the rest are validated by vim.gsplit
-  vim.validate{trimempty={trimempty, 'b', true}}
+function vim.split(s, sep, kwargs)
+  local plain
+  local trimempty = false
+  if type(kwargs) == 'boolean' then
+    -- Support old signature for backward compatibility
+    plain = kwargs
+  else
+    vim.validate { kwargs = {kwargs, 't', true} }
+    kwargs = kwargs or {}
+    plain = kwargs.plain
+    trimempty = kwargs.trimempty
+  end
+
   local t = {}
   local skip = trimempty
   for c in vim.gsplit(s, sep, plain) do
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 557923f648..8651a38025 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -237,8 +237,8 @@ describe('lua stdlib', function()
   end)
 
   it("vim.split", function()
-    local split = function(str, sep, plain, trimempty)
-      return exec_lua('return vim.split(...)', str, sep, plain, trimempty)
+    local split = function(str, sep, kwargs)
+      return exec_lua('return vim.split(...)', str, sep, kwargs)
     end
 
     local tests = {
@@ -259,9 +259,12 @@ describe('lua stdlib', function()
     }
 
     for _, t in ipairs(tests) do
-      eq(t[5], split(t[1], t[2], t[3], t[4]))
+      eq(t[5], split(t[1], t[2], {plain=t[3], trimempty=t[4]}))
     end
 
+    -- Test old signature
+    eq({'x', 'yz', 'oo', 'l'}, split("x*yz*oo*l", "*", true))
+
     local loops = {
       { "abc", ".-" },
     }
@@ -285,16 +288,10 @@ describe('lua stdlib', function()
             vim/shared.lua:0: in function <vim/shared.lua:0>]]),
       pcall_err(split, 'string', 1))
     eq(dedent([[
-        Error executing lua: vim/shared.lua:0: plain: expected boolean, got number
+        Error executing lua: vim/shared.lua:0: kwargs: expected table, got number
         stack traceback:
-            vim/shared.lua:0: in function 'gsplit'
             vim/shared.lua:0: in function <vim/shared.lua:0>]]),
       pcall_err(split, 'string', 'string', 1))
-    eq(dedent([[
-        Error executing lua: vim/shared.lua:0: trimempty: expected boolean, got number
-        stack traceback:
-            vim/shared.lua:0: in function <vim/shared.lua:0>]]),
-      pcall_err(split, 'string', 'string', false, 42))
   end)
 
   it('vim.trim', function()