Lua: vim.validate()

We often want to do type checking of public function arguments.

- test: Rename utility_function_spec.lua to vim_spec.lua
- .luacov: Map lua module names

.luacov

@@ -14,6 +14,9 @@ return {
     -- Relative (non-hidden) paths.
     '^[^/\\.]',
   },
+  modules = {
+    ['vim'] = 'runtime/lua/vim/shared.lua'
+  },
 }
 
 -- vim: ft=lua tw=80 sw=2 et

runtime/lua/vim/shared.lua

@@ -190,4 +190,78 @@ function vim.pesc(s)
   return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
 end
 
+--- Type checking validation function
+---
+--- Examples:
+--- <pre>
+---  validate({ arg={ { 'foo' }, 'table' }})                                     --> Nop
+---  validate({ arg={ 1, 'table' } })                                            --> error("arg: expected table, got number")
+---  validate({ arg1={ { 'foo' }, 'table' }, arg2={ 1, 'string' } })             --> error("arg2: expected string, got number")
+---  validate({ arg={ 3, function(a) return (a % 2) == 0  end, 'even number' }}) --> error("arg: expected even number, got 3")
+--- </pre>
+---
+---@param ... Table or list of table. That table is "argument_name = { validation_target, type_name (, whether nil is allowed) }"
+--- or "argument_name = { validation_target, validation function, expected_description }".
+--- The following can be used as type_names:
+---     - table or t
+---     - string or s
+---     - number or n
+---     - boolean or b
+---     - function or f
+---     - nil
+---     - thread
+---     - userdata
+function vim.validate(opt)
+  local function _type_name(t)
+    if t == 't' or t == 'table' then return 'table'  end
+    if t == 's' or t == 'string' then return 'string'  end
+    if t == 'n' or t == 'number' then return 'number'  end
+    if t == 'b' or t == 'boolean' then return 'boolean'  end
+    if t == 'f' or t == 'function' then return 'function' end
+    if t == 'c' then return 'callable' end
+    if t == 'nil' then return 'nil' end
+    if t == 'thread' or t == 'thread' then return 'thread'  end
+    if t == 'userdata' then return 'userdata' end
+    if vim.is_callable(t) then return end
+
+    error(string.format("Invalid type name '%s'. See \":help validate\" for more info.", t))
+  end
+  local function _check_type(target, expected_type)
+    if expected_type == 'callable' then
+      return vim.is_callable(target)
+    else
+      return type(target) == expected_type
+    end
+  end
+
+  for arg, v in pairs(opt) do
+    assert(type(arg) == 'string',string.format('Expected string, got %s', type(arg)))
+    assert(type(v) == 'table', string.format('Expected table, got %s', type(v)))
+
+    local actual_arg_type = type(v[1])
+    local expected_type = _type_name(v[2])
+
+    if expected_type then
+      if v[3] == true then
+        assert(_check_type(v[1], expected_type) or actual_arg_type == 'nil', string.format("%s: expected %s, got %s", arg, expected_type, actual_arg_type))
+      else
+        assert(_check_type(v[1], expected_type), string.format("%s: expected %s, got %s", arg, expected_type, actual_arg_type))
+      end
+    else
+      assert(v[2](v[1]), string.format("%s: expected %s, got %s", arg, v[3], v[1]))
+    end
+  end
+end
+
+--- Return whether an object can call be used as a function.
+---
+--@param f Any type of variable
+--@return Boolean
+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

test/functional/lua/vim_spec.lua

@@ -402,4 +402,57 @@ describe('lua stdlib', function()
     feed('<cr>')
     eq({3, NIL}, meths.get_var('yy'))
   end)
+
+  it('vim.validate', function()
+    eq(NIL, exec_lua("vim.validate({ arg1={ {}, 'table' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ {}, 't' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 't', true }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ { foo='foo' }, 't' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ { 'foo' }, 't' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ 'foo', 'string' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ 'foo', 's' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ '', 's' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 's', true }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ 1, 'number' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ 1, 'n' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ 0, 'n' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ 0.1, 'n' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 'n', true }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ true, 'boolean' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ true, 'b' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ false, 'b' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 'b', true }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ function()end, 'function' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ function()end, 'f' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 'f', true }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 'nil' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 'nil', true }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ coroutine.create(function()end), 'thread' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ nil, 'thread', true }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ {}, 't' } }, { arg2={ 'foo', 's' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ {}, 't' }, arg2={ 'foo', 's' }})"))
+    eq(NIL, exec_lua("vim.validate({ arg1={ 2, function(a) return (a % 2) == 0  end, 'even number' }})"))
+
+    eq("Error executing lua: .../shared.lua: arg1: expected table, got number", pcall_err(exec_lua, "vim.validate({ arg1={ 1, 't' }})"))
+    eq("Error executing lua: .../shared.lua: arg2: expected string, got number", pcall_err(exec_lua, "vim.validate({ arg1={ {}, 't' },  arg2={ 1, 's' }})"))
+    eq("Error executing lua: .../shared.lua: arg2: expected string, got nil", pcall_err(exec_lua, "vim.validate({ arg1={ {}, 't' },  arg2={ nil, 's' }})"))
+    eq("Error executing lua: .../shared.lua: arg2: expected string, got nil", pcall_err(exec_lua, "vim.validate({ arg1={ {}, 't' }, arg2={ nil, 's' }})"))
+    eq("Error executing lua: .../shared.lua: arg1: expected even number, got 3", pcall_err(exec_lua, "vim.validate({ arg1={ 3, function(a) return a == 1 end, 'even number' }})"))
+  end)
+
+  it('vim.is_callable', function()
+    eq(true, exec_lua("return vim.is_callable(function()end)"))
+    eq(true, exec_lua([[
+      local meta = { __call = function()end }
+      local function new_callable()
+        return setmetatable({}, meta)
+      end
+      local callable = new_callable()
+      return vim.is_callable(callable)
+    ]]))
+
+    eq(false, exec_lua("return vim.is_callable(1)"))
+    eq(false, exec_lua("return vim.is_callable('foo')"))
+    eq(false, exec_lua("return vim.is_callable({})"))
+  end)
 end)