diff options
Diffstat (limited to 'runtime/doc/lua.txt')
| -rw-r--r-- | runtime/doc/lua.txt | 321 |
1 files changed, 290 insertions, 31 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 97062e5986..98af84e1cb 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -17,9 +17,9 @@ an idea of what lurks beneath: > :lua print(vim.inspect(package.loaded)) Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the -"editor stdlib" (|functions| and Ex commands) and the |API|, all of which can -be used from Lua code. A good overview of using Lua in neovim is given by -https://github.com/nanotee/nvim-lua-guide. +"editor stdlib" (|builtin-functions| and Ex commands) and the |API|, all of +which can be used from Lua code. A good overview of using Lua in neovim is +given by https://github.com/nanotee/nvim-lua-guide. Module conflicts are resolved by "last wins". For example if both of these are on 'runtimepath': @@ -249,13 +249,15 @@ arguments separated by " " (space) instead of "\t" (tab). *:lua* :[range]lua {chunk} Executes Lua chunk {chunk}. - + if {chunk} starts with "=" the rest of the chunk is + evaluated as an expression and printed. `:lua =expr` + is equivalent to `:lua print(vim.inspect(expr))` Examples: > :lua vim.api.nvim_command('echo "Hello, Nvim!"') < To see the Lua version: > :lua print(_VERSION) < To see the LuaJIT version: > - :lua print(jit.version) + :lua =jit.version < *:lua-heredoc* :[range]lua << [endmarker] @@ -272,7 +274,7 @@ arguments separated by " " (space) instead of "\t" (tab). lua << EOF local linenr = vim.api.nvim_win_get_cursor(0)[1] local curline = vim.api.nvim_buf_get_lines( - 0, linenr, linenr + 1, false)[1] + 0, linenr - 1, linenr, false)[1] print(string.format("Current line [%d] has %d bytes", linenr, #curline)) EOF @@ -566,6 +568,26 @@ Example: TCP echo-server *tcp-server* end) print('TCP echo-server listening on port: '..server:getsockname().port) + +Multithreading *lua-loop-threading* + +Plugins can perform work in separate (os-level) threads using the threading +APIs in luv, for instance `vim.loop.new_thread`. Note that every thread +gets its own separate lua interpreter state, with no access to lua globals +in the main thread. Neither can the state of the editor (buffers, windows, +etc) be directly accessed from threads. + +A subset of the `vim.*` API is available in threads. This includes: + +- `vim.loop` with a separate event loop per thread. +- `vim.mpack` and `vim.json` (useful for serializing messages between threads) +- `require` in threads can use lua packages from the global |lua-package-path| +- `print()` and `vim.inspect` +- `vim.diff` +- most utility functions in `vim.*` for working with pure lua values + like `vim.split`, `vim.tbl_*`, `vim.list_*`, and so on. +- `vim.is_thread()` returns true from a non-main thread. + ------------------------------------------------------------------------------ VIM.HIGHLIGHT *lua-highlight* @@ -593,13 +615,33 @@ vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* - {on_visual} highlight when yanking visual selection (default `true`) - {event} event structure (default |v:event|) -vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclusive}) +vim.highlight.range({bufnr}, {ns}, {hlgroup}, {start}, {finish}, {opts}) *vim.highlight.range()* - Highlights the range between {start} and {finish} (tuples of {line,col}) - in buffer {bufnr} with the highlight group {higroup} using the namespace - {ns}. Optional arguments are the type of range (characterwise, linewise, - or blockwise, see |setreg|; default to characterwise) and whether the - range is inclusive (default false). + + Apply highlight group to range of text. + + Parameters: ~ + {bufnr} buffer number + {ns} namespace for highlights + {hlgroup} highlight group name + {start} starting position (tuple {line,col}) + {finish} finish position (tuple {line,col}) + {opts} optional parameters: + • `regtype`: type of range (characterwise, linewise, + or blockwise, see |setreg|), default `'v'` + • `inclusive`: range includes end position, default + `false` + • `priority`: priority of highlight, default + `vim.highlight.user` (see below) + +vim.highlight.priorities *vim.highlight.priorities* + + Table with default priorities used for highlighting: + • `syntax`: `50`, used for standard syntax highlighting + • `treesitter`: `100`, used for tree-sitter-based highlighting + • `diagnostics`: `150`, used for code analysis such as diagnostics + • `user`: `200`, used for user-triggered highlights such as LSP + document symbols or `on_yank` autocommands ------------------------------------------------------------------------------ VIM.REGEX *lua-regex* @@ -791,9 +833,9 @@ vim.stricmp({a}, {b}) *vim.stricmp()* respectively. vim.str_utfindex({str}[, {index}]) *vim.str_utfindex()* - Convert byte index to UTF-32 and UTF-16 indicies. If {index} is not - supplied, the length of the string is used. All indicies are zero-based. - Returns two values: the UTF-32 and UTF-16 indicies respectively. + Convert byte index to UTF-32 and UTF-16 indices. If {index} is not + supplied, the length of the string is used. All indices are zero-based. + Returns two values: the UTF-32 and UTF-16 indices respectively. Embedded NUL bytes are treated as terminating the string. Invalid UTF-8 bytes, and embedded surrogates are counted as one code @@ -913,6 +955,15 @@ vim.types *vim.types* `vim.types.dictionary` will not change or that `vim.types` table will only contain values for these three types. + *log_levels* *vim.log.levels* +Log levels are one of the values defined in `vim.log.levels`: + + vim.log.levels.DEBUG + vim.log.levels.ERROR + vim.log.levels.INFO + vim.log.levels.TRACE + vim.log.levels.WARN + ------------------------------------------------------------------------------ LUA-VIMSCRIPT BRIDGE *lua-vimscript* @@ -1229,19 +1280,32 @@ inspect({object}, {options}) *vim.inspect()* https://github.com/kikito/inspect.lua https://github.com/mpeterv/vinspect -notify({msg}, {log_level}, {opts}) *vim.notify()* - Notification provider +notify({msg}, {level}, {opts}) *vim.notify()* + Display a notification to the user. - Without a runtime, writes to :Messages + This function can be overridden by plugins to display + notifications using a custom provider (such as the system + notification provider). By default, writes to |:messages|. Parameters: ~ - {msg} string Content of the notification to show to - the user - {log_level} number|nil enum from vim.log.levels - {opts} table|nil additional options (timeout, etc) + {msg} string Content of the notification to show to the + user. + {level} number|nil One of the values from + |vim.log.levels|. + {opts} table|nil Optional parameters. Unused by default. - See also: ~ - :help nvim_notify +notify_once({msg}, {level}, {opts}) *vim.notify_once()* + Display a notification only one time. + + Like |vim.notify()|, but subsequent calls with the same + message will not display a notification. + + Parameters: ~ + {msg} string Content of the notification to show to the + user. + {level} number|nil One of the values from + |vim.log.levels|. + {opts} table|nil Optional parameters. Unused by default. on_key({fn}, {ns_id}) *vim.on_key()* Adds Lua function {fn} with namespace id {ns_id} as a listener @@ -1305,6 +1369,18 @@ paste({lines}, {phase}) *vim.paste()* See also: ~ |paste| +pretty_print({...}) *vim.pretty_print()* + Prints given arguments in human-readable format. Example: > + -- Print highlight group Normal and store it's contents in a variable. + local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true)) +< + + Return: ~ + given arguments. + + See also: ~ + |vim.inspect()| + region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* Get a table of lines with start, end columns for a region marked by two points @@ -1647,16 +1723,25 @@ validate({opt}) *vim.validate()* => error('arg1: expected even number, got 3') < + If multiple types are valid they can be given as a list. > + + vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} + => NOP (success) + + vim.validate{arg1={1, {'string', table'}}} + => error('arg1: expected string|table, got number') +< + Parameters: ~ - {opt} Map of parameter names to validations. Each key is - a parameter name; each value is a tuple in one of - these forms: + {opt} table 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") + • type_name: string|table type name, one of: + ("table", "t", "string", "s", "number", "n", + "boolean", "b", "function", "f", "nil", + "thread", "userdata") or list of them. • optional: (optional) boolean, if true, `nil` is valid @@ -1718,6 +1803,13 @@ Lua module: ui *lua-ui* input({opts}, {on_confirm}) *vim.ui.input()* Prompts the user for input + Example: > + + vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input) + vim.o.shiftwidth = tonumber(input) + end) +< + Parameters: ~ {opts} table Additional options. See |input()| • prompt (string|nil) Text of the prompt. @@ -1741,6 +1833,22 @@ select({items}, {opts}, {on_choice}) *vim.ui.select()* Prompts the user to pick a single item from a collection of entries + Example: > + + vim.ui.select({ 'tabs', 'spaces' }, { + prompt = 'Select tabs or spaces:', + format_item = function(item) + return "I'd like to choose " .. item + end, + }, function(choice) + if choice == 'spaces' then + vim.o.expandtab = true + else + vim.o.expandtab = false + end + end) +< + Parameters: ~ {items} table Arbitrary items {opts} table Additional options @@ -1760,4 +1868,155 @@ select({items}, {opts}, {on_choice}) *vim.ui.select()* 1-based index of `item` within `item` . `nil` if the user aborted the dialog. + +============================================================================== +Lua module: filetype *lua-filetype* + +add({filetypes}) *vim.filetype.add()* + Add new filetype mappings. + + Filetype mappings can be added either by extension or by + filename (either the "tail" or the full file path). The full + file path is checked first, followed by the file name. If a + match is not found using the filename, then the filename is + matched against the list of patterns (sorted by priority) + until a match is found. Lastly, if pattern matching does not + find a filetype, then the file extension is used. + + The filetype can be either a string (in which case it is used + as the filetype directly) or a function. If a function, it + takes the full path and buffer number of the file as arguments + (along with captures from the matched pattern, if any) and + should return a string that will be used as the buffer's + filetype. + + Filename patterns can specify an optional priority to resolve + cases when a file path matches multiple patterns. Higher + priorities are matched first. When omitted, the priority + defaults to 0. + + See $VIMRUNTIME/lua/vim/filetype.lua for more examples. + + Note that Lua filetype detection is only enabled when + |g:do_filetype_lua| is set to 1. + + Example: > + + vim.filetype.add({ + extension = { + foo = "fooscript", + bar = function(path, bufnr) + if some_condition() then + return "barscript" + end + return "bar" + end, + }, + filename = { + [".foorc"] = "toml", + ["/etc/foo/config"] = "toml", + }, + pattern = { + [".*‍/etc/foo/.*"] = "fooscript", + -- Using an optional priority + [".*‍/etc/foo/.*%.conf"] = { "dosini", { priority = 10 } }, + ["README.(%a+)$"] = function(path, bufnr, ext) + if ext == "md" then + return "markdown" + elseif ext == "rst" then + return "rst" + end + end, + }, + }) +< + + Parameters: ~ + {filetypes} table A table containing new filetype maps + (see example). + +match({name}, {bufnr}) *vim.filetype.match()* + Set the filetype for the given buffer from a file name. + + Parameters: ~ + {name} string File name (can be an absolute or relative + path) + {bufnr} number|nil The buffer to set the filetype for. + Defaults to the current buffer. + + +============================================================================== +Lua module: keymap *lua-keymap* + +del({modes}, {lhs}, {opts}) *vim.keymap.del()* + Remove an existing mapping. Examples: > + + vim.keymap.del('n', 'lhs') + + vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) +< + + Parameters: ~ + {opts} table A table of optional arguments: + • buffer: (number or boolean) Remove a mapping + from the given buffer. When "true" or 0, use the + current buffer. + + See also: ~ + |vim.keymap.set()| + +set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* + Add a new |mapping|. Examples: > + + -- Can add mapping to Lua functions + vim.keymap.set('n', 'lhs', function() print("real lua function") end) + + -- Can use it to map multiple modes + vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true }) + + -- Can add mapping for specific buffer + vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 }) + + -- Expr mappings + vim.keymap.set('i', '<Tab>', function() + return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" + end, { expr = true }) + -- <Plug> mappings + vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)') +< + + Note that in a mapping like: > + + vim.keymap.set('n', 'asdf', require('jkl').my_fun) +< + + the require('jkl') gets evaluated during this call in order to + access the function. If you want to avoid this cost at startup + you can wrap it in a function, for example: > + + vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end) +< + + Parameters: ~ + {mode} string|table Same mode short names as + |nvim_set_keymap()|. Can also be list of modes to + create mapping on multiple modes. + {lhs} string Left-hand side |{lhs}| of the mapping. + {rhs} string|function Right-hand side |{rhs}| of the + mapping. Can also be a Lua function. + {opts} table A table of |:map-arguments| such as + "silent". In addition to the options listed in + |nvim_set_keymap()|, this table also accepts the + following keys: + • replace_keycodes: (boolean, default true) When + both this and expr is "true", + |nvim_replace_termcodes()| is applied to the + result of Lua expr maps. + • remap: (boolean) Make the mapping recursive. + This is the inverse of the "noremap" option from + |nvim_set_keymap()|. Default `false` . + + See also: ~ + |nvim_set_keymap()| + vim:tw=78:ts=8:ft=help:norl: |