diff options
Diffstat (limited to 'runtime/doc/if_lua.txt')
| -rw-r--r-- | runtime/doc/if_lua.txt | 102 |
1 files changed, 78 insertions, 24 deletions
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index d1b8cd4856..a123041866 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -1,7 +1,7 @@ *if_lua.txt* Nvim - VIM REFERENCE MANUAL by Luis Carvalho + NVIM REFERENCE MANUAL Lua Interface to Nvim *lua* *Lua* @@ -9,18 +9,18 @@ Lua Interface to Nvim *lua* *Lua* Type |gO| to see the table of contents. ============================================================================== -1. Importing modules *lua-require* +Importing modules *lua-require* -Neovim lua interface automatically adjusts `package.path` and `package.cpath` -according to effective &runtimepath value. Adjustment happens after -'runtimepath' is changed. `package.path` is adjusted by simply appending -`/lua/?.lua` and `/lua/?/init.lua` to each directory from 'runtimepath' (`/` -is actually the first character of `package.config`). +Nvim automatically adjusts `package.path` and `package.cpath` according to +effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is +changed. `package.path` is adjusted by simply appending `/lua/?.lua` and +`/lua/?/init.lua` to each directory from 'runtimepath' (`/` is actually the +first character of `package.config`). -Similarly to `package.path`, modified directories from `runtimepath` are also -added to `package.cpath`. In this case, instead of appending `/lua/?.lua` and -`/lua/?/init.lua` to each runtimepath, all unique `?`-containing suffixes of -the existing `package.cpath` are used. Here is an example: +Similarly to `package.path`, modified directories from 'runtimepath' are also +added to `package.cpath`. In this case, instead of appending `/lua/?.lua` and +`/lua/?/init.lua` to each runtimepath, all unique `?`-containing suffixes of +the existing `package.cpath` are used. Example: 1. Given that - 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`; @@ -61,7 +61,7 @@ paths when path is removed from 'runtimepath', adding paths when they are added and reordering `package.path`/`package.cpath` content if 'runtimepath' was reordered. -Note 2: even though adjustments happens automatically Neovim does not track +Note 2: even though adjustments happens automatically Nvim does not track current values of `package.path` or `package.cpath`. If you happened to delete some paths from there you need to reset 'runtimepath' to make them readded. Just running `let &runtimepath = &runtimepath` should work. @@ -72,7 +72,7 @@ badly written plugins using shell which will not work with paths containing semicolons it is better to not have them in 'runtimepath' at all. ------------------------------------------------------------------------------ -1.1. Example of the plugin which uses lua modules: *lua-require-example* +Example of a plugin that uses lua modules *lua-require-example* The following example plugin adds a command `:MakeCharBlob` which transforms current buffer into a long `unsigned char` array. Lua contains transformation @@ -149,7 +149,7 @@ lua/charblob.lua: > } ============================================================================== -2. Commands *lua-commands* +Commands *lua-commands* *:lua* :[range]lua {chunk} @@ -157,7 +157,7 @@ lua/charblob.lua: > Examples: > - :lua vim.api.nvim_command('echo "Hello, Neovim!"') + :lua vim.api.nvim_command('echo "Hello, Nvim!"') < :[range]lua << {endmarker} @@ -230,27 +230,80 @@ All these commands execute a Lua chunk from either the command line (:lua and :luado) or a file (:luafile) with the given line [range]. Similarly to the Lua interpreter, each chunk has its own scope and so only global variables are shared between command calls. All Lua default libraries are available. In -addition, Lua "print" function has its output redirected to the Vim message +addition, Lua "print" function has its output redirected to the Nvim message area, with arguments separated by a white space instead of a tab. -Lua uses the "vim" module (see |lua-vim|) to issue commands to Neovim +Lua uses the "vim" module (see |lua-vim|) to issue commands to Nvim and manage buffers (|lua-buffer|) and windows (|lua-window|). However, procedures that alter buffer content, open new buffers, and change cursor position are restricted when the command is executed in the |sandbox|. ============================================================================== -2. The vim module *lua-vim* +The vim module *lua-vim* -Lua interfaces Vim through the "vim" module. Currently it only has `api` -submodule which is a table with all API functions. Descriptions of these -functions may be found in |api.txt|. +Lua interfaces Nvim through the "vim" module. Currently it has the `api` +submodule and some Nvim-specific utilities. + +------------------------------------------------------------------------------ +vim.api.* functions + +`vim.api` exposes the Nvim |API| as a table of Lua functions. All functions +are available. + +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.* utility functions + +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-tables|. 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. ============================================================================== -3. The luaeval function *lua-luaeval* *lua-eval* +The luaeval function *lua-luaeval* *lua-eval* *luaeval()* -The (dual) equivalent of "vim.eval" for passing Lua values to Vim is +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: @@ -262,7 +315,7 @@ semantically equivalent in Lua to: end Note that "_A" receives the argument to "luaeval". Lua nils, numbers, strings, -tables and booleans are converted to their Vim respective types. An error is +tables and booleans are converted to their respective VimL types. An error is thrown if conversion of any of the remaining Lua types is attempted. Note 2: lua tables are used as both dictionaries and lists, thus making it @@ -278,6 +331,7 @@ between these cases there is the following agreement: 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 |