From 678a51b1da0c0535299341e7a598c080adcf8553 Mon Sep 17 00:00:00 2001 From: Hirokazu Hata Date: Mon, 28 Oct 2019 20:52:18 +0900 Subject: [PATCH 1/5] 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 | 3 + runtime/lua/vim/shared.lua | 74 +++++++++++++++++++ ...tility_functions_spec.lua => vim_spec.lua} | 53 +++++++++++++ 3 files changed, 130 insertions(+) rename test/functional/lua/{utility_functions_spec.lua => vim_spec.lua} (82%) diff --git a/.luacov b/.luacov index 422783b858..f8eb28e3f7 100644 --- a/.luacov +++ b/.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 diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 7727fdbab0..9f656774a1 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -190,4 +190,78 @@ function vim.pesc(s) return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1') end +--- Type checking validation function +--- +--- Examples: +--- 
+---  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")
+---
+--- +---@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 diff --git a/test/functional/lua/utility_functions_spec.lua b/test/functional/lua/vim_spec.lua similarity index 82% rename from test/functional/lua/utility_functions_spec.lua rename to test/functional/lua/vim_spec.lua index 7dc97ee5af..cb1f027623 100644 --- a/test/functional/lua/utility_functions_spec.lua +++ b/test/functional/lua/vim_spec.lua @@ -402,4 +402,57 @@ describe('lua stdlib', function() feed('') 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) From 7aa4042d3bddf2f39d048b9ba1dd7adf2193d4eb Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 10 Nov 2019 19:58:14 -0800 Subject: [PATCH 2/5] Lua: vim.validate() --- runtime/lua/vim/shared.lua | 111 +++++++++++++++++-------------- test/functional/lua/vim_spec.lua | 79 +++++++++++++--------- 2 files changed, 108 insertions(+), 82 deletions(-) diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 9f656774a1..7d2523403a 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -190,68 +190,81 @@ function vim.pesc(s) return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1') end ---- Type checking validation function +--- Validates a parameter specification (types and values). --- --- Examples: --- 
----  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")
+---  function user.new(name, age, hobbies)
+---    vim.validate{
+---      name={name, 'string'},
+---      age={age, 'number'},
+---      hobbies={hobbies, 'table'},
+---    }
+---    ...
+---  end
+--
+---  vim.validate{ arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
+---     => NOP (success)
+---  vim.validate{arg1={1, 'table'}}
+---     => error("arg1: expected table, got number")
+---  vim.validate{arg1={{'foo'}, 'table'}, arg2={1, 'string'}}
+---     => error("arg2: expected string, got number")
+---  vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
+---     => error("arg1: expected even number, got 3")
 ---
--- ----@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 +--@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 - 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))) + 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 actual_arg_type = type(v[1]) - local expected_type = _type_name(v[2]) + local val = spec[1] -- Argument value. + local t = spec[2] -- Type name, or callable. + local optional = (true == spec[3]) - 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)) + if not vim.is_callable(t) then -- Check type name. + if not (optional or type(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], val)) end - else - assert(v[2](v[1]), string.format("%s: expected %s, got %s", arg, v[3], v[1])) end + return true end -end +end)() --- Return whether an object can call be used as a function. --- diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua index cb1f027623..a9c52bfcd9 100644 --- a/test/functional/lua/vim_spec.lua +++ b/test/functional/lua/vim_spec.lua @@ -404,40 +404,53 @@ describe('lua stdlib', function() 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' }})")) + exec_lua("vim.validate{arg1={{}, 'table' }}") + exec_lua("vim.validate{arg1={{}, 't' }}") + exec_lua("vim.validate{arg1={nil, 't', true }}") + exec_lua("vim.validate{arg1={{ foo='foo' }, 't' }}") + exec_lua("vim.validate{arg1={{ 'foo' }, 't' }}") + exec_lua("vim.validate{arg1={'foo', 'string' }}") + exec_lua("vim.validate{arg1={'foo', 's' }}") + exec_lua("vim.validate{arg1={'', 's' }}") + exec_lua("vim.validate{arg1={nil, 's', true }}") + exec_lua("vim.validate{arg1={1, 'number' }}") + exec_lua("vim.validate{arg1={1, 'n' }}") + exec_lua("vim.validate{arg1={0, 'n' }}") + exec_lua("vim.validate{arg1={0.1, 'n' }}") + exec_lua("vim.validate{arg1={nil, 'n', true }}") + exec_lua("vim.validate{arg1={true, 'boolean' }}") + exec_lua("vim.validate{arg1={true, 'b' }}") + exec_lua("vim.validate{arg1={false, 'b' }}") + exec_lua("vim.validate{arg1={nil, 'b', true }}") + exec_lua("vim.validate{arg1={function()end, 'function' }}") + exec_lua("vim.validate{arg1={function()end, 'f' }}") + exec_lua("vim.validate{arg1={nil, 'f', true }}") + exec_lua("vim.validate{arg1={nil, 'nil' }}") + exec_lua("vim.validate{arg1={nil, 'nil', true }}") + exec_lua("vim.validate{arg1={coroutine.create(function()end), 'thread' }}") + exec_lua("vim.validate{arg1={nil, 'thread', true }}") + exec_lua("vim.validate{arg1={{}, 't' }, arg2={ 'foo', 's' }}") + 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' }})")) + eq("Error executing lua: .../shared.lua: 1: expected table, got number", + pcall_err(exec_lua, "vim.validate{ 1, 'x' }")) + eq("Error executing lua: .../shared.lua: invalid type name: x", + pcall_err(exec_lua, "vim.validate{ arg1={ 1, 'x' }}")) + eq("Error executing lua: .../shared.lua: invalid type name: 1", + pcall_err(exec_lua, "vim.validate{ arg1={ 1, 1 }}")) + eq("Error executing lua: .../shared.lua: invalid type name: nil", + pcall_err(exec_lua, "vim.validate{ arg1={ 1 }}")) + + 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() From a0d992785feeefaea2810dcf08564fd8bea8cab9 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 10 Nov 2019 22:18:59 -0800 Subject: [PATCH 3/5] Lua: Use vim.validate() instead of assert() --- runtime/doc/if_lua.txt | 59 ++++++++++++++++++++++++++++++++ runtime/lua/vim/shared.lua | 47 ++++++++++++------------- test/functional/lua/vim_spec.lua | 29 ++++++++++------ 3 files changed, 102 insertions(+), 33 deletions(-) diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index bba43ea32c..7eef5d3903 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -847,4 +847,63 @@ pesc({s}) *vim.pesc()* See also: ~ https://github.com/rxi/lume +validate({opt}) *vim.validate()* + Validates a parameter specification (types and values). + + Usage example: > + + function user.new(name, age, hobbies) + vim.validate{ + name={name, 'string'}, + age={age, 'number'}, + hobbies={hobbies, 'table'}, + } + ... + end +< + + Examples with explicit argument values (can be run directly): > + + 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') +< + + Parameters: ~ + {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 + +is_callable({f}) *vim.is_callable()* + Returns true if object `f` can be called as a function. + + Parameters: ~ + {f} Any object + + Return: ~ + true if `f` is callable, else false + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 7d2523403a..e987e07a2a 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -47,9 +47,7 @@ end)() --@param plain If `true` use `sep` literally (passed to String.find) --@returns Iterator over the split components function vim.gsplit(s, sep, plain) - assert(type(s) == "string", string.format("Expected string, got %s", type(s))) - assert(type(sep) == "string", string.format("Expected string, got %s", type(sep))) - assert(type(plain) == "boolean" or type(plain) == "nil", string.format("Expected boolean or nil, got %s", type(plain))) + vim.validate{s={s,'s'},sep={sep,'s'},plain={plain,'b',true}} local start = 1 local done = false @@ -106,7 +104,7 @@ end --@param value Value to compare --@returns true if `t` contains `value` function vim.tbl_contains(t, value) - assert(type(t) == 'table', string.format("Expected table, got %s", type(t))) + vim.validate{t={t,'t'}} for _,v in ipairs(t) do if v == value then @@ -176,7 +174,7 @@ end --@param s String to trim --@returns String with whitespace removed from its beginning and end function vim.trim(s) - assert(type(s) == 'string', string.format("Expected string, got %s", type(s))) + vim.validate{s={s,'s'}} return s:match('^%s*(.*%S)') or '' end @@ -186,13 +184,13 @@ end --@param s String to escape --@returns %-escaped pattern string function vim.pesc(s) - assert(type(s) == 'string', string.format("Expected string, got %s", type(s))) + vim.validate{s={s,'s'}} return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1') end --- Validates a parameter specification (types and values). --- ---- Examples: +--- Usage example: --- 
 ---  function user.new(name, age, hobbies)
 ---    vim.validate{
@@ -202,26 +200,29 @@ end
 ---    }
 ---    ...
 ---  end
---
----  vim.validate{ arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
+---
+--- +--- Examples with explicit argument values (can be run directly): +--- 
+---  vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
 ---     => NOP (success)
+---
 ---  vim.validate{arg1={1, 'table'}}
----     => error("arg1: expected table, got number")
----  vim.validate{arg1={{'foo'}, 'table'}, arg2={1, 'string'}}
----     => error("arg2: expected string, got number")
+---     => 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")
+---     => error('arg1: expected even number, got 3')
 ---
--- --@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} +--- 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} +--- 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 @@ -234,14 +235,14 @@ vim.validate = (function() ['boolean']='boolean', ['function']='function', ['callable']='callable', ['nil']='nil', ['thread']='thread', ['userdata']='userdata', } - local function type_name(t) + 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) + local function _is_type(val, t) return t == 'callable' and vim.is_callable(val) or type(val) == t end @@ -255,21 +256,21 @@ vim.validate = (function() local optional = (true == spec[3]) if not vim.is_callable(t) then -- Check type name. - if not (optional or type(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))) + 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], val)) + error(string.format("%s: expected %s, got %s", param_name, (spec[3] or '?'), val)) end end return true end end)() ---- Return whether an object can call be used as a function. +--- Returns true if object `f` can be called as a function. --- ---@param f Any type of variable ---@return Boolean +--@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) diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua index a9c52bfcd9..a25ae1d2c0 100644 --- a/test/functional/lua/vim_spec.lua +++ b/test/functional/lua/vim_spec.lua @@ -230,12 +230,12 @@ describe('lua stdlib', function() end -- Validates args. - eq(true, pcall(split, 'string', 'string', nil)) - eq('Error executing lua: .../shared.lua: Expected string, got number', - pcall_err(split, 1, 'string', nil)) - eq('Error executing lua: .../shared.lua: Expected string, got number', - pcall_err(split, 'string', 1, nil)) - eq('Error executing lua: .../shared.lua: Expected boolean or nil, got number', + eq(true, pcall(split, 'string', 'string')) + eq('Error executing lua: .../shared.lua: s: expected string, got number', + pcall_err(split, 1, 'string')) + eq('Error executing lua: .../shared.lua: sep: expected string, got number', + pcall_err(split, 'string', 1)) + eq('Error executing lua: .../shared.lua: plain: expected boolean, got number', pcall_err(split, 'string', 'string', 1)) end) @@ -256,7 +256,7 @@ describe('lua stdlib', function() end -- Validates args. - eq('Error executing lua: .../shared.lua: Expected string, got number', + eq('Error executing lua: .../shared.lua: s: expected string, got number', pcall_err(trim, 2)) end) @@ -301,7 +301,7 @@ describe('lua stdlib', function() eq('foo%%%-bar', exec_lua([[return vim.pesc(vim.pesc('foo-bar'))]])) -- Validates args. - eq("Error executing lua: .../shared.lua: Expected string, got number", + eq('Error executing lua: .../shared.lua: s: expected string, got number', pcall_err(exec_lua, [[return vim.pesc(2)]])) end) @@ -441,16 +441,25 @@ describe('lua stdlib', function() eq("Error executing lua: .../shared.lua: invalid type name: nil", pcall_err(exec_lua, "vim.validate{ arg1={ 1 }}")) + -- Validated parameters are required by default. + eq("Error executing lua: .../shared.lua: arg1: expected string, got nil", + pcall_err(exec_lua, "vim.validate{ arg1={ nil, 's' }}")) + -- Explicitly required. + eq("Error executing lua: .../shared.lua: arg1: expected string, got nil", + pcall_err(exec_lua, "vim.validate{ arg1={ nil, 's', false }}")) + 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'}}")) + 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'}}")) + 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'}}")) + eq("Error executing lua: .../shared.lua: arg1: expected ?, got 3", + pcall_err(exec_lua, "vim.validate{arg1={3, function(a) return a == 1 end}}")) end) it('vim.is_callable', function() From 7a3d3257db623e1fe7a9dee9944bdecedf615931 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 10 Nov 2019 22:21:05 -0800 Subject: [PATCH 4/5] fix nvim__buf_stats Accidentally renamed in 1cb467454782. --- src/nvim/api/buffer.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 10250be044..257e02ec4f 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -1257,7 +1257,7 @@ Array nvim_buf_get_virtual_text(Buffer buffer, Integer lnum, Error *err) return chunks; } -Dictionary nvim__uf_stats(Buffer buffer, Error *err) +Dictionary nvim__buf_stats(Buffer buffer, Error *err) { Dictionary rv = ARRAY_DICT_INIT; From f59e1f58a2ed24198fb1653edeffb6ab5ec2bbdb Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 10 Nov 2019 23:07:36 -0800 Subject: [PATCH 5/5] Lua: mark some functions as "private" Problem: scripts/gen_vimdoc.py gets confused and tries to generate docs for `fn_index` and `func`. Solution: Rename them to be private. --- src/nvim/lua/vim.lua | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua index 1ebdde99d5..2b4c5486c7 100644 --- a/src/nvim/lua/vim.lua +++ b/src/nvim/lua/vim.lua @@ -261,14 +261,14 @@ end -- vim.fn.{func}(...) -local function fn_index(t, key) - local function func(...) +local function _fn_index(t, key) + local function _fn(...) return vim.call(key, ...) end - t[key] = func - return func + t[key] = _fn + return _fn end -local fn = setmetatable({}, {__index=fn_index}) +local fn = setmetatable({}, {__index=_fn_index}) local module = { _update_package_paths = _update_package_paths,