diff options
| -rw-r--r-- | runtime/doc/if_lua.txt | 237 | ||||
| -rw-r--r-- | src/nvim/lua/vim.lua | 59 |
2 files changed, 176 insertions, 120 deletions
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index b97341e319..57f5da7cd0 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -258,6 +258,75 @@ position are restricted when the command is executed in the |sandbox|. ============================================================================== +luaeval() *lua-luaeval* *lua-eval* + *luaeval()* + +The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is +"luaeval". "luaeval" takes an expression string and an optional argument used +for _A inside expression and returns the result of the expression. It is +semantically equivalent in Lua to: +> + local chunkheader = "local _A = select(1, ...) return " + function luaeval (expstr, arg) + local chunk = assert(loadstring(chunkheader .. expstr, "luaeval")) + return chunk(arg) -- return typval + end + +Lua nils, numbers, strings, tables and booleans are converted to their +respective VimL types. An error is thrown if conversion of any other Lua types +is attempted. + +The magic global "_A" contains the second argument to luaeval(). + +Example: > + :echo luaeval('_A[1] + _A[2]', [40, 2]) + 42 + :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123') + foo + +Lua tables are used as both dictionaries and lists, so it is impossible to +determine whether empty table is meant to be empty list or empty dictionary. +Additionally lua does not have integer numbers. To distinguish between these +cases there is the following agreement: + +0. Empty table is empty list. +1. Table with N incrementally growing integral numbers, starting from 1 and + ending with N is considered to be a list. +2. Table with string keys, none of which contains NUL byte, is considered to + be a dictionary. +3. Table with string keys, at least one of which contains NUL byte, is also + considered to be a dictionary, but this time it is converted to + a |msgpack-special-map|. + *lua-special-tbl* +4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point + value: + - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to + a floating-point 1.0. Note that by default integral lua numbers are + converted to |Number|s, non-integral are converted to |Float|s. This + variant allows integral |Float|s. + - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty + dictionary, `{[vim.type_idx]=vim.types.dictionary, [42]=1, a=2}` is + converted to a dictionary `{'a': 42}`: non-string keys are ignored. + Without `vim.type_idx` key tables with keys not fitting in 1., 2. or 3. + are errors. + - `{[vim.type_idx]=vim.types.list}` is converted to an empty list. As well + as `{[vim.type_idx]=vim.types.list, [42]=1}`: integral keys that do not + form a 1-step sequence from 1 to N are ignored, as well as all + non-integral keys. + +Examples: > + + :echo luaeval('math.pi') + :function Rand(x,y) " random uniform between x and y + : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y}) + : endfunction + :echo Rand(1,10) + +Note that currently second argument to `luaeval` undergoes VimL to lua +conversion, so changing containers in lua do not affect values in VimL. Return +value is also always converted. When converting, |msgpack-special-dict|s are + +============================================================================== vim.* *lua-vim* *lua-stdlib* The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes @@ -304,53 +373,16 @@ For example, to use the "nvim_get_current_line()" API function, call ------------------------------------------------------------------------------ vim.* builtin functions -vim.deepcopy({object}) *vim.deepcopy* - 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. - -vim.gsplit({s}, {sep}, {plain}) *vim.gsplit* - Split a given string by a separator. Returns an iterator of the - split components. The separator can be a lua pattern, see - https://www.lua.org/pil/20.2.html - Setting {plain} to `true` turns off pattern matching, as it is passed - to `string:find`, see - http://lua-users.org/wiki/StringLibraryTutorial - - Parameters:~ - {s} String: String to split - {sep} String: Separator pattern. If empty, split by chars. - {plain} Boolean: If false, match {sep} verbatim - - Return:~ - Iterator of strings, which are the components of {s} after - splitting - -vim.split({s}, {sep}, {plain}) *vim.split* - Split a given string by a separator. Returns a table containing the - split components. The separator can be a lua pattern, see - https://www.lua.org/pil/20.2.html - Setting {plain} to `true` turns off pattern matching, as it is passed - to `string:find`, see - http://lua-users.org/wiki/StringLibraryTutorial - - Parameters:~ - {s} String: String to split - {sep} String: Separator pattern. If empty, split by chars. - {plain} Boolean: If false, match {sep} verbatim - - Return:~ - Table of strings, which are the components of {s} after - splitting +vim.inspect({object}, {options}) *vim.inspect* + Return a human-readable representation of the passed object. See + https://github.com/kikito/inspect.lua + for details and possible options. vim.stricmp(a, b) *lua-vim.stricmp* Function used for case-insensitive string comparison. Takes two string arguments and returns 0, 1 or -1 if strings are equal, a is greater then b or a is lesser then b respectively. -vim.trim({string}) *vim.trim* - Returns the string with all leading and trailing whitespace removed. - vim.type_idx *lua-vim.type_idx* Type index for use in |lua-special-tbl|. Specifying one of the values from |lua-vim.types| allows typing the empty table (it is @@ -386,86 +418,69 @@ vim.types *lua-vim.types* `vim.types.dictionary` will not change or that `vim.types` table will only contain values for these three types. ------------------------------------------------------------------------------- -vim.* runtime functions +============================================================================== +Vim Lua Functions *lua-vim* -Those functions are only available after the runtime files have been loaded. -In particular, they are not available when using `nvim -u NONE`. +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. -vim.inspect({object}, {options}) *vim.inspect* - Return a human-readable representation of the passed object. See - https://github.com/kikito/inspect.lua - for details and possible options. + [1]https://www.lua.org/pil/20.2.html. -============================================================================== -luaeval() *lua-luaeval* *lua-eval* - *luaeval()* + [2]http://lua-users.org/wiki/StringLibraryTutorial -The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is -"luaeval". "luaeval" takes an expression string and an optional argument used -for _A inside expression and returns the result of the expression. It is -semantically equivalent in Lua to: -> - local chunkheader = "local _A = select(1, ...) return " - function luaeval (expstr, arg) - local chunk = assert(loadstring(chunkheader .. expstr, "luaeval")) - return chunk(arg) -- return typval - end + 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) -Lua nils, numbers, strings, tables and booleans are converted to their -respective VimL types. An error is thrown if conversion of any other Lua types -is attempted. + Return: ~ + An iterator over the split components -The magic global "_A" contains the second argument to luaeval(). +split({s}, {sep}, {plain}) *vim.split()* + Split a string by a given separator. -Example: > - :echo luaeval('_A[1] + _A[2]', [40, 2]) - 42 - :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123') - foo + Examples: -Lua tables are used as both dictionaries and lists, so it is impossible to -determine whether empty table is meant to be empty list or empty dictionary. -Additionally lua does not have integer numbers. To distinguish between these -cases there is the following agreement: + - split(":aa::b:", ":") returns {'','aa','','bb',''} + - split("axaby", "ab?") returns {'','x','y'} + - split(x*yz*o, "*", true) returns {'x','yz','o'} -0. Empty table is empty list. -1. Table with N incrementally growing integral numbers, starting from 1 and - ending with N is considered to be a list. -2. Table with string keys, none of which contains NUL byte, is considered to - be a dictionary. -3. Table with string keys, at least one of which contains NUL byte, is also - considered to be a dictionary, but this time it is converted to - a |msgpack-special-map|. - *lua-special-tbl* -4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point - value: - - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to - a floating-point 1.0. Note that by default integral lua numbers are - converted to |Number|s, non-integral are converted to |Float|s. This - variant allows integral |Float|s. - - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty - dictionary, `{[vim.type_idx]=vim.types.dictionary, [42]=1, a=2}` is - converted to a dictionary `{'a': 42}`: non-string keys are ignored. - Without `vim.type_idx` key tables with keys not fitting in 1., 2. or 3. - are errors. - - `{[vim.type_idx]=vim.types.list}` is converted to an empty list. As well - as `{[vim.type_idx]=vim.types.list, [42]=1}`: integral keys that do not - form a 1-step sequence from 1 to N are ignored, as well as all - non-integral keys. + 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()|) -Examples: > + Return: ~ + An array containing the components of the split. - :echo luaeval('math.pi') - :function Rand(x,y) " random uniform between x and y - : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y}) - : endfunction - :echo Rand(1,10) +trim({s}) *vim.trim()* + Trim the whitespaces from a string. A whitespace is everything + that matches the lua pattern '%s', see -Note that currently second argument to `luaeval` undergoes VimL to lua -conversion, so changing containers in lua do not affect values in VimL. Return -value is also always converted. When converting, |msgpack-special-dict|s are -treated specially. + https://www.lua.org/pil/20.2.html -============================================================================== - vim:tw=78:ts=8:et:ft=help:norl: + Parameters: ~ + {s} String The string to trim + + Return: ~ + 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 + copy. For a non-table object, that just means a usual copy of + the object, while for a table all subtables are copied + recursively. + + Parameters: ~ + {orig} Table The table to copy + + Return: ~ + A new table where the keys and values are deepcopies of + the keys and values from the original table. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua index 1a7aec6cc6..9e592e444b 100644 --- a/src/nvim/lua/vim.lua +++ b/src/nvim/lua/vim.lua @@ -154,6 +154,18 @@ 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. +--- +--- [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") @@ -162,7 +174,7 @@ local function gsplit(s, sep, plain) local start = 1 local done = false - local function pass(i, j, ...) + local function _pass(i, j, ...) if i then assert(j+1 > start, "Infinite loop detected") local seg = s:sub(start, i - 1) @@ -182,26 +194,55 @@ local function gsplit(s, sep, plain) if start == #s then done = true end - return pass(start+1, start) + return _pass(start+1, start) end - return pass(s:find(sep, start, plain)) + return _pass(s:find(sep, start, plain)) end end +--- Split a string by a given separator. +--- +--- Examples: +--- +--- * split(":aa::b:", ":") returns {'','aa','','bb',''} +--- +--- * split("axaby", "ab?") returns {'','x','y'} +--- +--- * split(x*yz*o, "*", true) returns {'x','yz','o'} +--- +--@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 local function trim(s) assert(type(s) == "string", "Only strings can be trimmed") local result = s:gsub("^%s+", ""):gsub("%s+$", "") return result end -local deepcopy +--- 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) +local function _id(v) return v end @@ -213,10 +254,10 @@ local deepcopy_funcs = { end return copy end, - number = id, - string = id, - ['nil'] = id, - boolean = id, + number = _id, + string = _id, + ['nil'] = _id, + boolean = _id, } deepcopy = function(orig) |