lua/shared: share deepcopy() with test/*

deepcopy() was duplicated in test/helpers.lua

runtime/doc/if_lua.txt

@@ -472,37 +472,52 @@ trim({s})                                                         *vim.trim()*
                     The string with all whitespaces trimmed from its beginning
                     and end
 
+
+
+
 deepcopy({orig})                                              *vim.deepcopy()*
-                Performs a deep copy of the given object, and returns that
+                Returns a deep copy of the given object. Non-table objects are
-                copy. For a non-table object, that just means a usual copy of
+                copied as in a typical Lua assignment, whereas table objects
-                the object, while for a table all subtables are copied
+                are copied recursively.
-                recursively.
 
                 Parameters: ~
-                    {orig}  Table The table to copy
+                    {orig}  Table to copy
 
                 Return: ~
-                    A new table where the keys and values are deepcopies of
+                    New table of copied keys and (nested) values.
-                    the keys and values from the original table.
-
-
-
 
 tbl_contains({t}, {value})                                *vim.tbl_contains()*
-                TODO: Documentation
+                Checks if a list-like (vector) table contains `value` .
+
+                Parameters: ~
+                    {t}      Table to check
+                    {value}  Value to compare
+
+                Return: ~
+                    true if `t` contains `value`
 
 tbl_extend({behavior}, {...})                               *vim.tbl_extend()*
+                Merges two or more map-like tables.
+
                 Parameters: ~
                     {behavior}  Decides what to do if a key is found in more
                                 than one map:
                                 - "error": raise an error
                                 - "keep": use value from the leftmost map
                                 - "force": use value from the rightmost map
+                    {...}       Two or more map-like tables.
 
                 See also: ~
                     |extend()|
 
 tbl_flatten({t})                                           *vim.tbl_flatten()*
-                TODO: Documentation
+                Creates a copy of a list-like table such that any nested
+                tables are "unrolled" and appended to the result.
+
+                Parameters: ~
+                    {t}  List-like table
+
+                Return: ~
+                    Flattened copy of the given list-like table.
 
  vim:tw=78:ts=8:ft=help:norl:

runtime/lua/vim/shared.lua

@@ -1,9 +1,43 @@
---- Shared functions
+-- Functions shared by Nvim and its test-suite.
---    - Used by Nvim and tests
+--
---    - Can run in vanilla Lua (do not require a running instance of Nvim)
+-- The singular purpose of this module is to share code with the Nvim
+-- test-suite. If, in the future, Nvim itself is used to run the test-suite
+-- instead of "vanilla Lua", these functions could move to src/nvim/lua/vim.lua
 
 
--- Checks if a list-like (vector) table contains `value`.
+--- 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.
+---
+--@param orig Table to copy
+--@returns New table of copied keys and (nested) values.
+local function deepcopy(orig)
+  error()
+end
+local function _id(v)
+  return v
+end
+local deepcopy_funcs = {
+  table = function(orig)
+    local copy = {}
+    for k, v in pairs(orig) do
+      copy[deepcopy(k)] = deepcopy(v)
+    end
+    return copy
+  end,
+  number = _id,
+  string = _id,
+  ['nil'] = _id,
+  boolean = _id,
+}
+deepcopy = function(orig)
+  return deepcopy_funcs[type(orig)](orig)
+end
+
+--- Checks if a list-like (vector) table contains `value`.
+---
+--@param t Table to check
+--@param value Value to compare
+--@returns true if `t` contains `value`
 local function tbl_contains(t, value)
   if type(t) ~= 'table' then
     error('t must be a table')
@@ -16,14 +50,15 @@ local function tbl_contains(t, value)
   return false
 end
 
--- Merges two or more map-like tables.
+--- Merges two or more map-like tables.
---
+---
 --@see |extend()|
---
+---
 --@param behavior Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
 ---      - "keep":  use value from the leftmost map
 ---      - "force": use value from the rightmost map
+--@param ... Two or more map-like tables.
 local function tbl_extend(behavior, ...)
   if (behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force') then
     error('invalid "behavior": '..tostring(behavior))
@@ -46,7 +81,11 @@ local function tbl_extend(behavior, ...)
   return ret
 end
 
--- Flattens a list-like table: unrolls and appends nested tables to table `t`.
+--- Creates a copy of a list-like table such that any nested tables are
+--- "unrolled" and appended to the result.
+---
+--@param t List-like table
+--@returns Flattened copy of the given list-like table.
 local function tbl_flatten(t)
   -- From https://github.com/premake/premake-core/blob/master/src/base/table.lua
   local result = {}
@@ -66,6 +105,7 @@ local function tbl_flatten(t)
 end
 
 local module = {
+  deepcopy = deepcopy,
   tbl_contains = tbl_contains,
   tbl_extend = tbl_extend,
   tbl_flatten = tbl_flatten,

src/nvim/lua/vim.lua

@@ -1,10 +1,10 @@
 -- Nvim-Lua stdlib: the `vim` module (:help lua-stdlib)
 --
 -- Lua code lives in one of three places:
---    1. The runtime (`runtime/lua/vim/`). For "nice to have" features, e.g.
+--    1. runtime/lua/vim/ (the runtime): For "nice to have" features, e.g. the
---       the `inspect` and `lpeg` modules.
+--       `inspect` and `lpeg` modules.
---    2. The `vim.shared` module: code shared between Nvim and its test-suite.
+--    2. runtime/lua/vim/shared.lua: Code shared between Nvim and tests.
---    3. Compiled-into Nvim itself (`src/nvim/lua/`).
+--    3. src/nvim/lua/: Compiled-into Nvim itself.
 --
 -- Guideline: "If in doubt, put it in the runtime".
 --
@@ -231,38 +231,6 @@ local function trim(s)
   return result
 end
 
---- Performs a deep copy of the given object, and returns that copy.
---- For a non-table object, that just means a usual copy of the object,
---- while for a table all subtables are copied recursively.
---@param orig Table The table to copy
---@returns A new table where the keys and values are deepcopies of the keys
---- and values from the original table.
-local function deepcopy(orig)
-  error()
-end
-
-local function _id(v)
-  return v
-end
-
-local deepcopy_funcs = {
-  table = function(orig)
-    local copy = {}
-    for k, v in pairs(orig) do
-      copy[deepcopy(k)] = deepcopy(v)
-    end
-    return copy
-  end,
-  number = _id,
-  string = _id,
-  ['nil'] = _id,
-  boolean = _id,
-}
-
-deepcopy = function(orig)
-  return deepcopy_funcs[type(orig)](orig)
-end
-
 local function __index(t, key)
   if key == 'inspect' then
     t.inspect = require('vim.inspect')
@@ -282,7 +250,6 @@ local module = {
   trim = trim,
   split = split,
   gsplit = gsplit,
-  deepcopy = deepcopy,
 }
 
 setmetatable(module, {

test/helpers.lua

@@ -336,30 +336,6 @@ local function shallowcopy(orig)
   return copy
 end
 
-local deepcopy
-
-local function id(v)
-  return v
-end
-
-local deepcopy_funcs = {
-  table = function(orig)
-    local copy = {}
-    for k, v in pairs(orig) do
-      copy[deepcopy(k)] = deepcopy(v)
-    end
-    return copy
-  end,
-  number = id,
-  string = id,
-  ['nil'] = id,
-  boolean = id,
-}
-
-deepcopy = function(orig)
-  return deepcopy_funcs[type(orig)](orig)
-end
-
 local REMOVE_THIS = {}
 
 local function mergedicts_copy(d1, d2)
@@ -728,7 +704,6 @@ local module = {
   check_logs = check_logs,
   concat_tables = concat_tables,
   dedent = dedent,
-  deepcopy = deepcopy,
   dictdiff = dictdiff,
   eq = eq,
   expect_err = expect_err,