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 @@ -257,146 +257,6 @@ procedures that alter buffer content, open new buffers, and change cursor position are restricted when the command is executed in the |sandbox|. -============================================================================== -vim.* *lua-vim* *lua-stdlib* - -The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes -various functions and sub-modules. It is always loaded, thus require("vim") -is unnecessary. - -You can peek at the module properties: > - - :lua print(vim.inspect(vim)) - -Result is something like this: > - - { - _os_proc_children = , - _os_proc_info = , - ... - api = { - nvim__id = , - nvim__id_array = , - ... - }, - deepcopy = , - gsplit = , - ... - } - -To find documentation on e.g. the "deepcopy" function: > - - :help vim.deepcopy - -Note that underscore-prefixed functions (e.g. "_os_proc_children") are -internal/private and must not be used by plugins. - ------------------------------------------------------------------------------- -vim.api.* functions - -`vim.api` exposes the full Nvim |API| as a table of Lua functions. - -For example, to use the "nvim_get_current_line()" API function, call -"vim.api.nvim_get_current_line()": > - - print(tostring(vim.api.nvim_get_current_line())) - ------------------------------------------------------------------------------- -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.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 - unclear whether empty lua table represents empty list or empty array) - and forcing integral numbers to be |Float|. See |lua-special-tbl| for - more details. - -vim.val_idx *lua-vim.val_idx* - Value index for tables representing |Float|s. A table representing - floating-point value 1.0 looks like this: > - { - [vim.type_idx] = vim.types.float, - [vim.val_idx] = 1.0, - } -< See also |lua-vim.type_idx| and |lua-special-tbl|. - -vim.types *lua-vim.types* - Table with possible values for |lua-vim.type_idx|. Contains two sets - of key-value pairs: first maps possible values for |lua-vim.type_idx| - to human-readable strings, second maps human-readable type names to - values for |lua-vim.type_idx|. Currently contains pairs for `float`, - `array` and `dictionary` types. - - Note: one must expect that values corresponding to `vim.types.float`, - `vim.types.array` and `vim.types.dictionary` fall under only two - following assumptions: - 1. Value may serve both as a key and as a value in a table. Given the - properties of lua tables this basically means “value is not `nil`”. - 2. For each value in `vim.types` table `vim.types[vim.types[value]]` - is the same as `value`. - No other restrictions are put on types, and it is not guaranteed that - values corresponding to `vim.types.float`, `vim.types.array` and - `vim.types.dictionary` will not change or that `vim.types` table will - only contain values for these three types. - ------------------------------------------------------------------------------- -vim.* runtime functions - -Those functions are only available after the runtime files have been loaded. -In particular, they are not available when using `nvim -u NONE`. - -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. - ============================================================================== luaeval() *lua-luaeval* *lua-eval* *luaeval()* @@ -465,7 +325,162 @@ Examples: > 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. ============================================================================== - vim:tw=78:ts=8:et:ft=help:norl: +vim.* *lua-vim* *lua-stdlib* + +The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes +various functions and sub-modules. It is always loaded, thus require("vim") +is unnecessary. + +You can peek at the module properties: > + + :lua print(vim.inspect(vim)) + +Result is something like this: > + + { + _os_proc_children = , + _os_proc_info = , + ... + api = { + nvim__id = , + nvim__id_array = , + ... + }, + deepcopy = , + gsplit = , + ... + } + +To find documentation on e.g. the "deepcopy" function: > + + :help vim.deepcopy + +Note that underscore-prefixed functions (e.g. "_os_proc_children") are +internal/private and must not be used by plugins. + +------------------------------------------------------------------------------ +vim.api.* functions + +`vim.api` exposes the full Nvim |API| as a table of Lua functions. + +For example, to use the "nvim_get_current_line()" API function, call +"vim.api.nvim_get_current_line()": > + + print(tostring(vim.api.nvim_get_current_line())) + +------------------------------------------------------------------------------ +vim.* builtin functions + +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.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 + unclear whether empty lua table represents empty list or empty array) + and forcing integral numbers to be |Float|. See |lua-special-tbl| for + more details. + +vim.val_idx *lua-vim.val_idx* + Value index for tables representing |Float|s. A table representing + floating-point value 1.0 looks like this: > + { + [vim.type_idx] = vim.types.float, + [vim.val_idx] = 1.0, + } +< See also |lua-vim.type_idx| and |lua-special-tbl|. + +vim.types *lua-vim.types* + Table with possible values for |lua-vim.type_idx|. Contains two sets + of key-value pairs: first maps possible values for |lua-vim.type_idx| + to human-readable strings, second maps human-readable type names to + values for |lua-vim.type_idx|. Currently contains pairs for `float`, + `array` and `dictionary` types. + + Note: one must expect that values corresponding to `vim.types.float`, + `vim.types.array` and `vim.types.dictionary` fall under only two + following assumptions: + 1. Value may serve both as a key and as a value in a table. Given the + properties of lua tables this basically means “value is not `nil`”. + 2. For each value in `vim.types` table `vim.types[vim.types[value]]` + is the same as `value`. + No other restrictions are put on types, and it is not guaranteed that + values corresponding to `vim.types.float`, `vim.types.array` and + `vim.types.dictionary` will not change or that `vim.types` table will + only contain values for these three types. + +============================================================================== +Vim Lua Functions *lua-vim* + +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. + + [1]https://www.lua.org/pil/20.2.html. + + [2]http://lua-users.org/wiki/StringLibraryTutorial + + 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) + + Return: ~ + An iterator over the split components + +split({s}, {sep}, {plain}) *vim.split()* + 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'} + + 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()|) + + Return: ~ + An array containing the components of the split. + +trim({s}) *vim.trim()* + 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 + + 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)