refactor(vim.gsplit): remove "keepsep"

string.gmatch() is superior, use that instead.

4 files changed, 27 insertions, 34 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index a1fb7aa344..2baae3a123 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1659,12 +1659,18 @@ gsplit({s}, {sep}, {opts})                                      *vim.gsplit()*
        end
 <
 
+    If you want to also inspect the separator itself (instead of discarding
+    it), use |string.gmatch()|. Example: >lua
+
+       for word, num in ('foo111bar222'):gmatch('([^0-9]*)(d*)') do
+         print(('word: s num: s'):format(word, num))
+       end
+<
+
     Parameters: ~
-      • {s}     (string) String to split
-      • {sep}   (string) Separator or pattern
+      • {s}     string String to split
+      • {sep}   string Separator or pattern
       • {opts}  (table|nil) Keyword arguments |kwargs|:
-                • keepsep: (boolean) Return segments matching `sep` instead of
-                  discarding them.
                 • plain: (boolean) Use `sep` literally (as in string.find).
                 • trimempty: (boolean) Discard empty segments at start and end
                   of the sequence.
@@ -1673,6 +1679,7 @@ gsplit({s}, {sep}, {opts})                                      *vim.gsplit()*
         (function) Iterator over the split components
 
     See also: ~
+      • |string.gmatch()|
       • |vim.split()|
       • |luaref-patterns|
       • https://www.lua.org/pil/20.2.html
@@ -1749,7 +1756,6 @@ split({s}, {sep}, {opts})                                        *vim.split()*
       split("axaby", "ab?")                   --> {'','x','y'}
       split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
       split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
-      split("|x|y|z|", "|", {keepsep=true})   --> {'|', 'x', '|', 'y', '|', 'z', '|'}
 <
 
     Parameters: ~
@@ -1763,6 +1769,7 @@ split({s}, {sep}, {opts})                                        *vim.split()*
 
     See also: ~
       • |vim.gsplit()|
+      • |string.gmatch()|
 
 startswith({s}, {prefix})                                   *vim.startswith()*
     Tests if `s` starts with `prefix`.
@@ -2625,7 +2632,7 @@ cmp({v1}, {v2})                                            *vim.version.cmp()*
         (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`.
 
 eq({v1}, {v2})                                              *vim.version.eq()*
-    Returns `true` if the given versions are equal.
+    Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage.
 
     Parameters: ~
       • {v1}  Version|number[]
@@ -2635,7 +2642,7 @@ eq({v1}, {v2})                                              *vim.version.eq()*
         (boolean)
 
 gt({v1}, {v2})                                              *vim.version.gt()*
-    Returns `true` if `v1 > v2` .
+    Returns `true` if `v1 > v2` . See |vim.version.cmp()| for usage.
 
     Parameters: ~
       • {v1}  Version|number[]
@@ -2654,7 +2661,7 @@ last({versions})                                          *vim.version.last()*
         Version ?|ni
 
 lt({v1}, {v2})                                              *vim.version.lt()*
-    Returns `true` if `v1 < v2` .
+    Returns `true` if `v1 < v2` . See |vim.version.cmp()| for usage.
 
     Parameters: ~
       • {v1}  Version|number[]
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 9eb49cdfac..884929e33a 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -66,6 +66,14 @@ end)()
 ---   end
 ---   </pre>
 ---
+--- If you want to also inspect the separator itself (instead of discarding it), use
+--- |string.gmatch()|. Example:
+---   <pre>lua
+---   for word, num in ('foo111bar222'):gmatch('([^0-9]*)(%d*)') do
+---     print(('word: %s num: %s'):format(word, num))
+---   end
+---   </pre>
+---
 --- @see |string.gmatch()|
 --- @see |vim.split()|
 --- @see |luaref-patterns|
@@ -75,27 +83,22 @@ end)()
 --- @param s string String to split
 --- @param sep string Separator or pattern
 --- @param opts (table|nil) Keyword arguments |kwargs|:
----       - keepsep: (boolean) Include segments matching `sep` instead of discarding them.
 ---       - plain: (boolean) Use `sep` literally (as in string.find).
 ---       - trimempty: (boolean) Discard empty segments at start and end of the sequence.
 ---@return fun():string|nil (function) Iterator over the split components
 function vim.gsplit(s, sep, opts)
   local plain
   local trimempty = false
-  local keepsep = false
   if type(opts) == 'boolean' then
     plain = opts -- For backwards compatibility.
   else
     vim.validate({ s = { s, 's' }, sep = { sep, 's' }, opts = { opts, 't', true } })
     opts = opts or {}
-    plain, trimempty, keepsep = opts.plain, opts.trimempty, opts.keepsep
-    assert(not trimempty or not keepsep, 'keepsep+trimempty not supported')
+    plain, trimempty = opts.plain, opts.trimempty
   end
 
   local start = 1
   local done = false
-  local sepseg = nil -- Last matched `sep` segment.
-  local sepesc = plain and vim.pesc(sep) or sep
 
   -- For `trimempty`:
   local empty_start = true -- Only empty segments seen so far.
@@ -105,9 +108,6 @@ function vim.gsplit(s, sep, opts)
   local function _pass(i, j, ...)
     if i then
       assert(j + 1 > start, 'Infinite loop detected')
-      if keepsep then
-        sepseg = s:match(sepesc, start)
-      end
       local seg = s:sub(start, i - 1)
       start = j + 1
       return seg, ...
@@ -126,10 +126,6 @@ function vim.gsplit(s, sep, opts)
       local seg = nonemptyseg
       nonemptyseg = nil
       return seg
-    elseif keepsep and sepseg then
-      local seg = sepseg
-      sepseg = nil
-      return seg
     elseif done or (s == '' and sep == '') then
       return nil
     elseif sep == '' then
@@ -171,17 +167,16 @@ end
 ---  split("axaby", "ab?")                   --> {'','x','y'}
 ---  split("x*yz*o", "*", {plain=true})      --> {'x','yz','o'}
 ---  split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
----  split("|x|y|z|", "|", {keepsep=true})   --> {'|', 'x', '|', 'y', '|', 'z', '|'}
 --- </pre>
 ---
 ---@see |vim.gsplit()|
+---@see |string.gmatch()|
 ---
 ---@param s string String to split
 ---@param sep string Separator or pattern
 ---@param opts (table|nil) Keyword arguments |kwargs| accepted by |vim.gsplit()|
 ---@return string[] List of split components
 function vim.split(s, sep, opts)
-  -- TODO(justinmk): deprecate vim.split in favor of vim.totable(vim.gsplit())
   local t = {}
   for c in vim.gsplit(s, sep, opts) do
     table.insert(t, c)
diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 43001c195c..3aacf3d4e0 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -65,6 +65,8 @@ local M = {}
 local Version = {}
 Version.__index = Version
 
+--- @private
+---
 --- Compares prerelease strings: per semver, number parts must be must be treated as numbers:
 --- "pre1.10" is greater than "pre1.2". https://semver.org/#spec-item-11
 local function cmp_prerel(prerel1, prerel2)
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 4cf38a1567..a0428ed933 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -329,14 +329,6 @@ describe('lua stdlib', function()
       matches("Infinite loop detected", pcall_err(vim.split, t[1], t[2]))
     end
 
-    -- `keepsep`
-    eq({ '', '.', '', '.', 'aa', '.', 'bb', '.', 'cc', '.', 'dd', '.', 'ee', '.', '', },
-      vim.split('..aa.bb.cc.dd.ee.', '%.', {keepsep=true}))
-    eq({ '..aa', '1', '.bb', '2', '', '2', '.cc.', '9', '', },
-      vim.split('..aa1.bb22.cc.9', '%d', {keepsep=true}))
-    eq({ '..aa', '1', '.bb', '22', '.cc.', '9', '', },
-      vim.split('..aa1.bb22.cc.9', '%d+', {keepsep=true}))
-
     -- Validates args.
     eq(true, pcall(vim.split, 'string', 'string'))
     matches('s: expected string, got number',
@@ -345,9 +337,6 @@ describe('lua stdlib', function()
       pcall_err(vim.split, 'string', 1))
     matches('opts: expected table, got number',
       pcall_err(vim.split, 'string', 'string', 1))
-    -- Not supported (yet).
-    matches('keepsep%+trimempty not supported',
-      pcall_err(vim.split, 'foo bar', ' ', {keepsep=true, trimempty=true}))
   end)
 
   it('vim.trim', function()