lua/shared: share more stuff

Leave trim() in vim.lua, because gen_vimdoc.py needs at least one
function in there, else it gets confused...

3 files changed, 113 insertions, 114 deletions

diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index e7e28e041d..7f90074ff0 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -422,69 +422,70 @@ vim.types						*lua-vim.types*
 ==============================================================================
 Lua module: vim                                                      *lua-vim*
 
-gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
-                Split a string by a given separator. The separator can be a
-                lua pattern, see [1]. Used by |vim.split()|, see there for
-                some examples. See [2] for usage of the plain parameter.
-
-                [1]https://www.lua.org/pil/20.2.html.
-
-                [2]http://lua-users.org/wiki/StringLibraryTutorial
+trim({s})                                                         *vim.trim()*
+                Trim whitespace (Lua pattern "%%s") from both sides of a
+                string.
 
                 Parameters: ~
-                    {s}      String The string to split
-                    {sep}    String The separator to use
-                    {plain}  Boolean If `true` , use the separator literally
-                             (passed as an argument to String.find)
+                    {s}  String to trim
 
                 Return: ~
-                    An iterator over the split components
+                    String with whitespace removed from its beginning and end
 
-split({s}, {sep}, {plain})                                       *vim.split()*
-                Split a string by a given separator.
+                See also: ~
+                    https://www.lua.org/pil/20.2.html
 
-                Examples: >
 
-                  split(":aa::b:", ":")     --> {'','aa','','bb',''}
-                  split("axaby", "ab?")     --> {'','x','y'}
-                  split(x*yz*o, "*", true)  --> {'x','yz','o'}
-<
+
+
+deepcopy({orig})                                              *vim.deepcopy()*
+                Returns a deep copy of the given object. Non-table objects are
+                copied as in a typical Lua assignment, whereas table objects
+                are copied recursively.
 
                 Parameters: ~
-                    {s}      String The string to split
-                    {sep}    String The separator to use (see |vim.gsplit()|)
-                    {plain}  Boolean If `true` , use the separator literally
-                             (see |vim.gsplit()|)
+                    {orig}  Table to copy
 
                 Return: ~
-                    An array containing the components of the split.
-
-trim({s})                                                         *vim.trim()*
-                Trim the whitespaces from a string. A whitespace is everything
-                that matches the lua pattern '%s', see
+                    New table of copied keys and (nested) values.
 
-                https://www.lua.org/pil/20.2.html
+gsplit({s}, {sep}, {plain})                                     *vim.gsplit()*
+                Splits a string at each instance of a separator.
 
                 Parameters: ~
-                    {s}  String The string to trim
+                    {s}      String to split
+                    {sep}    Separator string or pattern
+                    {plain}  If `true` use `sep` literally (passed to
+                             String.find)
 
                 Return: ~
-                    The string with all whitespaces trimmed from its beginning
-                    and end
-
+                    Iterator over the split components
 
+                See also: ~
+                    |vim.split()|
+                    https://www.lua.org/pil/20.2.html
+                    http://lua-users.org/wiki/StringLibraryTutorial
 
+split({s}, {sep}, {plain})                                       *vim.split()*
+                Splits a string at each instance of a separator.
 
-deepcopy({orig})                                              *vim.deepcopy()*
-                Returns a deep copy of the given object. Non-table objects are
-                copied as in a typical Lua assignment, whereas table objects
-                are copied recursively.
+                Examples: >
+                 split(":aa::b:", ":")     --> {'','aa','','bb',''}
+                 split("axaby", "ab?")     --> {'','x','y'}
+                 split(x*yz*o, "*", true)  --> {'x','yz','o'}
+<
 
                 Parameters: ~
-                    {orig}  Table to copy
+                    {s}      String to split
+                    {sep}    Separator string or pattern
+                    {plain}  If `true` use `sep` literally (passed to
+                             String.find)
 
                 Return: ~
-                    New table of copied keys and (nested) values.
+                    List-like table of the split components.
+
+                See also: ~
+                    |vim.gsplit()|
 
 tbl_contains({t}, {value})                                *vim.tbl_contains()*
                 Checks if a list-like (vector) table contains `value` .
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index f5d7a51724..07f9f52e5c 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -33,6 +33,70 @@ deepcopy = function(orig)
   return deepcopy_funcs[type(orig)](orig)
 end
 
+--- Splits a string at each instance of a separator.
+---
+--@see |vim.split()|
+--@see https://www.lua.org/pil/20.2.html
+--@see http://lua-users.org/wiki/StringLibraryTutorial
+---
+--@param s String to split
+--@param sep Separator string or pattern
+--@param plain If `true` use `sep` literally (passed to String.find)
+--@returns Iterator over the split components
+local function gsplit(s, sep, plain)
+  assert(type(s) == "string")
+  assert(type(sep) == "string")
+  assert(type(plain) == "boolean" or type(plain) == "nil")
+
+  local start = 1
+  local done = false
+
+  local function _pass(i, j, ...)
+    if i then
+      assert(j+1 > start, "Infinite loop detected")
+      local seg = s:sub(start, i - 1)
+      start = j + 1
+      return seg, ...
+    else
+      done = true
+      return s:sub(start)
+    end
+  end
+
+  return function()
+    if done then
+      return
+    end
+    if sep == '' then
+      if start == #s then
+        done = true
+      end
+      return _pass(start+1, start)
+    end
+    return _pass(s:find(sep, start, plain))
+  end
+end
+
+--- Splits a string at each instance of a separator.
+---
+--- Examples:
+--- <pre>
+---  split(":aa::b:", ":")     --> {'','aa','','bb',''}
+---  split("axaby", "ab?")     --> {'','x','y'}
+---  split(x*yz*o, "*", true)  --> {'x','yz','o'}
+--- </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)
+--@returns List-like table of the split components.
+local function split(s,sep,plain)
+  local t={} for c in gsplit(s, sep, plain) do table.insert(t,c) end
+  return t
+end
+
 --- Checks if a list-like (vector) table contains `value`.
 ---
 --@param t Table to check
@@ -106,6 +170,8 @@ end
 
 local module = {
   deepcopy = deepcopy,
+  gsplit = gsplit,
+  split = split,
   tbl_contains = tbl_contains,
   tbl_extend = tbl_extend,
   tbl_flatten = tbl_flatten,
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index 3c1a9a86d0..38a8795680 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -154,80 +154,14 @@ local function _update_package_paths()
   last_nvim_paths = cur_nvim_paths
 end
 
----Split a string by a given separator. The separator can be a lua pattern, see [1].
----Used by |vim.split()|, see there for some examples. See [2]
----for usage of the plain parameter.
+--- Trim whitespace (Lua pattern "%%s") from both sides of a string.
 ---
---- [1] https://www.lua.org/pil/20.2.html.
----
---- [2] http://lua-users.org/wiki/StringLibraryTutorial
---@param s String The string to split
---@param sep String The separator to use
---@param plain Boolean If `true`, use the separator literally
----(passed as an argument to String.find)
---@returns An iterator over the split components
-local function gsplit(s, sep, plain)
-  assert(type(s) == "string")
-  assert(type(sep) == "string")
-  assert(type(plain) == "boolean" or type(plain) == "nil")
-
-  local start = 1
-  local done = false
-
-  local function _pass(i, j, ...)
-    if i then
-      assert(j+1 > start, "Infinite loop detected")
-      local seg = s:sub(start, i - 1)
-      start = j + 1
-      return seg, ...
-    else
-      done = true
-      return s:sub(start)
-    end
-  end
-
-  return function()
-    if done then
-      return
-    end
-    if sep == '' then
-      if start == #s then
-        done = true
-      end
-      return _pass(start+1, start)
-    end
-    return _pass(s:find(sep, start, plain))
-  end
-end
-
---- Split a string by a given separator.
----
---- Examples:
---- <pre>
----  split(":aa::b:", ":")     --> {'','aa','','bb',''}
----  split("axaby", "ab?")     --> {'','x','y'}
----  split(x*yz*o, "*", true)  --> {'x','yz','o'}
---- </pre>
----
---@param s String The string to split
---@param sep String The separator to use (see |vim.gsplit()|)
---@param plain Boolean If `true`, use the separator literally
----(see |vim.gsplit()|)
---@returns An array containing the components of the split.
-local function split(s,sep,plain)
-  local t={} for c in gsplit(s, sep, plain) do table.insert(t,c) end
-  return t
-end
-
---- Trim the whitespaces from a string.  A whitespace is everything that
---- matches the lua pattern '%%s', see
----
---- https://www.lua.org/pil/20.2.html
---@param s String The string to trim
---@returns The string with all whitespaces trimmed from its beginning and end
+--@see https://www.lua.org/pil/20.2.html
+--@param s String to trim
+--@returns String with whitespace removed from its beginning and end
 local function trim(s)
-  assert(type(s) == "string", "Only strings can be trimmed")
-  local result = s:gsub("^%s+", ""):gsub("%s+$", "")
+  assert(type(s) == 'string', 'Only strings can be trimmed')
+  local result = s:gsub('^%s+', ''):gsub('%s+$', '')
   return result
 end
 
@@ -248,8 +182,6 @@ local module = {
   _os_proc_info = _os_proc_info,
   _system = _system,
   trim = trim,
-  split = split,
-  gsplit = gsplit,
 }
 
 setmetatable(module, {