Merge remote-tracking branch 'upstream/master' into libcallnr

1 files changed, 396 insertions, 61 deletions

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index cd6f8a04d8..6e427665f2 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -4,34 +4,51 @@
 -- 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
 
+local vim = vim or {}
 
 --- 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.
+--- Functions are naively copied, so functions in the copied table point to the
+--- same functions as those in the input table. Userdata and threads are not
+--- copied and will throw an error.
 ---
 --@param orig Table to copy
 --@returns New table of copied keys and (nested) values.
-local function deepcopy(orig)
-  error(orig)
-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)
+function vim.deepcopy(orig) end  -- luacheck: no unused
+vim.deepcopy = (function()
+  local function _id(v)
+    return v
+  end
+
+  local deepcopy_funcs = {
+    table = function(orig)
+      local copy = {}
+
+      if vim._empty_dict_mt ~= nil and getmetatable(orig) == vim._empty_dict_mt then
+        copy = vim.empty_dict()
+      end
+
+      for k, v in pairs(orig) do
+        copy[vim.deepcopy(k)] = vim.deepcopy(v)
+      end
+      return copy
+    end,
+    number = _id,
+    string = _id,
+    ['nil'] = _id,
+    boolean = _id,
+    ['function'] = _id,
+  }
+
+  return function(orig)
+    local f = deepcopy_funcs[type(orig)]
+    if f then
+      return f(orig)
+    else
+      error("Cannot deepcopy object of type "..type(orig))
     end
-    return copy
-  end,
-  number = _id,
-  string = _id,
-  ['nil'] = _id,
-  boolean = _id,
-}
-deepcopy = function(orig)
-  return deepcopy_funcs[type(orig)](orig)
-end
+  end
+end)()
 
 --- Splits a string at each instance of a separator.
 ---
@@ -43,10 +60,8 @@ end
 --@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")
+function vim.gsplit(s, sep, plain)
+  vim.validate{s={s,'s'},sep={sep,'s'},plain={plain,'b',true}}
 
   local start = 1
   local done = false
@@ -64,7 +79,7 @@ local function gsplit(s, sep, plain)
   end
 
   return function()
-    if done then
+    if done or (s == '' and sep == '') then
       return
     end
     if sep == '' then
@@ -92,20 +107,81 @@ end
 --@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
+function vim.split(s,sep,plain)
+  local t={} for c in vim.gsplit(s, sep, plain) do table.insert(t,c) end
   return t
 end
 
+--- Return a list of all keys used in a table.
+--- However, the order of the return table of keys is not guaranteed.
+---
+--@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
+---
+--@param t Table
+--@returns list of keys
+function vim.tbl_keys(t)
+  assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
+
+  local keys = {}
+  for k, _ in pairs(t) do
+    table.insert(keys, k)
+  end
+  return keys
+end
+
+--- Return a list of all values used in a table.
+--- However, the order of the return table of values is not guaranteed.
+---
+--@param t Table
+--@returns list of values
+function vim.tbl_values(t)
+  assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
+
+  local values = {}
+  for _, v in pairs(t) do
+    table.insert(values, v)
+  end
+  return values
+end
+
+--- Apply a function to all values of a table.
+---
+--@param func function or callable table
+--@param t table
+function vim.tbl_map(func, t)
+  vim.validate{func={func,'c'},t={t,'t'}}
+
+  local rettab = {}
+  for k, v in pairs(t) do
+    rettab[k] = func(v)
+  end
+  return rettab
+end
+
+--- Filter a table using a predicate function
+---
+--@param func function or callable table
+--@param t table
+function vim.tbl_filter(func, t)
+  vim.validate{func={func,'c'},t={t,'t'}}
+
+  local rettab = {}
+  for _, entry in pairs(t) do
+    if func(entry) then
+      table.insert(rettab, entry)
+    end
+  end
+  return rettab
+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')
-  end
+function vim.tbl_contains(t, value)
+  vim.validate{t={t,'t'}}
+
   for _,v in ipairs(t) do
     if v == value then
       return true
@@ -114,25 +190,38 @@ local function tbl_contains(t, value)
   return false
 end
 
---- 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, ...)
+-- Returns true if the table is empty, and contains no indexed or keyed values.
+--
+--@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
+--
+--@param t Table to check
+function vim.tbl_isempty(t)
+  assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
+  return next(t) == nil
+end
+
+local function tbl_extend(behavior, deep_extend, ...)
   if (behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force') then
     error('invalid "behavior": '..tostring(behavior))
   end
+
+  if select('#', ...) < 2 then
+    error('wrong number of arguments (given '..tostring(1 + select('#', ...))..', expected at least 3)')
+  end
+
   local ret = {}
+  if vim._empty_dict_mt ~= nil and getmetatable(select(1, ...)) == vim._empty_dict_mt then
+    ret = vim.empty_dict()
+  end
+
   for i = 1, select('#', ...) do
     local tbl = select(i, ...)
+    vim.validate{["after the second argument"] = {tbl,'t'}}
     if tbl then
       for k, v in pairs(tbl) do
-        if behavior ~= 'force' and ret[k] ~= nil then
+        if type(v) == 'table' and deep_extend and not vim.tbl_islist(v) then
+          ret[k] = tbl_extend(behavior, true, ret[k] or vim.empty_dict(), v)
+        elseif behavior ~= 'force' and ret[k] ~= nil then
           if behavior == 'error' then
             error('key found in more than one map: '..k)
           end  -- Else behavior is "keep".
@@ -145,13 +234,103 @@ local function tbl_extend(behavior, ...)
   return ret
 end
 
+--- 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.
+function vim.tbl_extend(behavior, ...)
+  return tbl_extend(behavior, false, ...)
+end
+
+--- Merges recursively two or more map-like tables.
+---
+--@see |tbl_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.
+function vim.tbl_deep_extend(behavior, ...)
+  return tbl_extend(behavior, true, ...)
+end
+
+--- Deep compare values for equality
+function vim.deep_equal(a, b)
+  if a == b then return true end
+  if type(a) ~= type(b) then return false end
+  if type(a) == 'table' then
+    -- TODO improve this algorithm's performance.
+    for k, v in pairs(a) do
+      if not vim.deep_equal(v, b[k]) then
+        return false
+      end
+    end
+    for k, v in pairs(b) do
+      if not vim.deep_equal(v, a[k]) then
+        return false
+      end
+    end
+    return true
+  end
+  return false
+end
+
+--- Add the reverse lookup values to an existing table.
+--- For example:
+--- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`
+--
+--Do note that it *modifies* the input.
+--@param o table The table to add the reverse to.
+function vim.tbl_add_reverse_lookup(o)
+  local keys = vim.tbl_keys(o)
+  for _, k in ipairs(keys) do
+    local v = o[k]
+    if o[v] then
+      error(string.format("The reverse lookup found an existing value for %q while processing key %q", tostring(v), tostring(k)))
+    end
+    o[v] = k
+  end
+  return o
+end
+
+--- Extends a list-like table with the values of another list-like table.
+---
+--- NOTE: This mutates dst!
+---
+--@see |vim.tbl_extend()|
+---
+--@param dst list which will be modified and appended to.
+--@param src list from which values will be inserted.
+--@param start Start index on src. defaults to 1
+--@param finish Final index on src. defaults to #src
+--@returns dst
+function vim.list_extend(dst, src, start, finish)
+  vim.validate {
+    dst = {dst, 't'};
+    src = {src, 't'};
+    start = {start, 'n', true};
+    finish = {finish, 'n', true};
+  }
+  for i = start or 1, finish or #src do
+    table.insert(dst, src[i])
+  end
+  return dst
+end
+
 --- Creates a copy of a list-like table such that any nested tables are
 --- "unrolled" and appended to the result.
 ---
+--@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
+---
 --@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
+function vim.tbl_flatten(t)
   local result = {}
   local function _tbl_flatten(_t)
     local n = #_t
@@ -168,34 +347,190 @@ local function tbl_flatten(t)
   return result
 end
 
+--- Determine whether a Lua table can be treated as an array.
+---
+--- An empty table `{}` will default to being treated as an array.
+--- Use `vim.emtpy_dict()` to create a table treated as an
+--- empty dict. Empty tables returned by `rpcrequest()` and
+--- `vim.fn` functions can be checked using this function
+--- whether they represent empty API arrays and vimL lists.
+---
+--@param t Table
+--@returns `true` if array-like table, else `false`.
+function vim.tbl_islist(t)
+  if type(t) ~= 'table' then
+    return false
+  end
+
+  local count = 0
+
+  for k, _ in pairs(t) do
+    if type(k) == "number" then
+      count = count + 1
+    else
+      return false
+    end
+  end
+
+  if count > 0 then
+    return true
+  else
+    -- TODO(bfredl): in the future, we will always be inside nvim
+    -- then this check can be deleted.
+    if vim._empty_dict_mt == nil then
+      return nil
+    end
+    return getmetatable(t) ~= vim._empty_dict_mt
+  end
+end
+
+--- Counts the number of non-nil values in table `t`.
+---
+--- <pre>
+--- vim.tbl_count({ a=1, b=2 }) => 2
+--- vim.tbl_count({ 1, 2 }) => 2
+--- </pre>
+---
+--@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
+--@param t Table
+--@returns Number that is the number of the value in table
+function vim.tbl_count(t)
+  vim.validate{t={t,'t'}}
+
+  local count = 0
+  for _ in pairs(t) do count = count + 1 end
+  return count
+end
+
 --- Trim whitespace (Lua pattern "%s") from both sides of a string.
 ---
 --@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')
+function vim.trim(s)
+  vim.validate{s={s,'s'}}
   return s:match('^%s*(.*%S)') or ''
 end
 
---- Escapes magic chars in a Lua pattern string.
+--- Escapes magic chars in a Lua pattern.
 ---
 --@see https://github.com/rxi/lume
 --@param s  String to escape
 --@returns  %-escaped pattern string
-local function pesc(s)
-  assert(type(s) == 'string')
+function vim.pesc(s)
+  vim.validate{s={s,'s'}}
   return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
 end
 
-local module = {
-  deepcopy = deepcopy,
-  gsplit = gsplit,
-  pesc = pesc,
-  split = split,
-  tbl_contains = tbl_contains,
-  tbl_extend = tbl_extend,
-  tbl_flatten = tbl_flatten,
-  trim = trim,
-}
-return module
+--- Tests if `s` starts with `prefix`.
+---
+--@param s (string) a string
+--@param prefix (string) a prefix
+--@return (boolean) true if `prefix` is a prefix of s
+function vim.startswith(s, prefix)
+  vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; }
+  return s:sub(1, #prefix) == prefix
+end
+
+--- Tests if `s` ends with `suffix`.
+---
+--@param s (string) a string
+--@param suffix (string) a suffix
+--@return (boolean) true if `suffix` is a suffix of s
+function vim.endswith(s, suffix)
+  vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; }
+  return #suffix == 0 or s:sub(-#suffix) == suffix
+end
+
+--- Validates a parameter specification (types and values).
+---
+--- Usage example:
+--- <pre>
+---  function user.new(name, age, hobbies)
+---    vim.validate{
+---      name={name, 'string'},
+---      age={age, 'number'},
+---      hobbies={hobbies, 'table'},
+---    }
+---    ...
+---  end
+--- </pre>
+---
+--- Examples with explicit argument values (can be run directly):
+--- <pre>
+---  vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
+---     => NOP (success)
+---
+---  vim.validate{arg1={1, 'table'}}
+---     => error('arg1: expected table, got number')
+---
+---  vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
+---     => error('arg1: expected even number, got 3')
+--- </pre>
+---
+--@param opt Map of parameter names to validations. Each key is a parameter
+---          name; each value is a tuple in one of these forms:
+---          1. (arg_value, type_name, optional)
+---             - arg_value: argument value
+---             - type_name: string type name, one of: ("table", "t", "string",
+---               "s", "number", "n", "boolean", "b", "function", "f", "nil",
+---               "thread", "userdata")
+---             - optional: (optional) boolean, if true, `nil` is valid
+---          2. (arg_value, fn, msg)
+---             - arg_value: argument value
+---             - fn: any function accepting one argument, returns true if and
+---               only if the argument is valid
+---             - msg: (optional) error string if validation fails
+function vim.validate(opt) end  -- luacheck: no unused
+vim.validate = (function()
+  local type_names = {
+    t='table', s='string', n='number', b='boolean', f='function', c='callable',
+    ['table']='table', ['string']='string', ['number']='number',
+    ['boolean']='boolean', ['function']='function', ['callable']='callable',
+    ['nil']='nil', ['thread']='thread', ['userdata']='userdata',
+  }
+  local function _type_name(t)
+    local tname = type_names[t]
+    if tname == nil then
+      error(string.format('invalid type name: %s', tostring(t)))
+    end
+    return tname
+  end
+  local function _is_type(val, t)
+    return t == 'callable' and vim.is_callable(val) or type(val) == t
+  end
+
+  return function(opt)
+    assert(type(opt) == 'table', string.format('opt: expected table, got %s', type(opt)))
+    for param_name, spec in pairs(opt) do
+      assert(type(spec) == 'table', string.format('%s: expected table, got %s', param_name, type(spec)))
+
+      local val = spec[1]   -- Argument value.
+      local t = spec[2]     -- Type name, or callable.
+      local optional = (true == spec[3])
+
+      if not vim.is_callable(t) then  -- Check type name.
+        if (not optional or val ~= nil) and not _is_type(val, _type_name(t)) then
+          error(string.format("%s: expected %s, got %s", param_name, _type_name(t), type(val)))
+        end
+      elseif not t(val) then  -- Check user-provided validation function.
+        error(string.format("%s: expected %s, got %s", param_name, (spec[3] or '?'), val))
+      end
+    end
+    return true
+  end
+end)()
+
+--- Returns true if object `f` can be called as a function.
+---
+--@param f Any object
+--@return true if `f` is callable, else false
+function vim.is_callable(f)
+  if type(f) == 'function' then return true end
+  local m = getmetatable(f)
+  if m == nil then return false end
+  return type(m.__call) == 'function'
+end
+
+return vim
+-- vim:sw=2 ts=2 et