diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/api.txt | 171 | ||||
| -rw-r--r-- | runtime/doc/builtin.txt | 22 | ||||
| -rw-r--r-- | runtime/doc/deprecated.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/dev_style.txt | 25 | ||||
| -rw-r--r-- | runtime/doc/diagnostic.txt | 106 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 11 | ||||
| -rw-r--r-- | runtime/doc/index.txt | 5 | ||||
| -rw-r--r-- | runtime/doc/lsp.txt | 258 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 660 | ||||
| -rw-r--r-- | runtime/doc/map.txt | 7 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 48 | ||||
| -rw-r--r-- | runtime/doc/pattern.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/quickref.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/starting.txt | 317 | ||||
| -rw-r--r-- | runtime/doc/syntax.txt | 172 | ||||
| -rw-r--r-- | runtime/doc/treesitter.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/usr_21.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/various.txt | 8 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 15 | ||||
| -rw-r--r-- | runtime/doc/windows.txt | 2 |
20 files changed, 1013 insertions, 836 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 50fe60a0fc..7c669e3c9d 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -426,6 +426,14 @@ Two ways to create a floating window: To close it use |nvim_win_close()| or a command such as |:close|. +To check whether a window is floating, check whether the `relative` option in +its config is non-empty: > + + if vim.api.nvim_win_get_config(window_id).relative ~= '' then + -- window with this window_id is floating + end +> + Buffer text can be highlighted by typical mechanisms (syntax highlighting, |api-highlights|). The |hl-NormalFloat| group highlights normal text; 'winhighlight' can be used as usual to override groups locally. Floats inherit @@ -836,8 +844,11 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* Treated as single-width even if it isn't. • highlights: (boolean) Return highlight information. + • use_winbar: (boolean) Evaluate winbar instead of + statusline. • use_tabline: (boolean) Evaluate tabline instead of statusline. When |TRUE|, {winid} is ignored. + Mutually exclusive with {use_winbar}. Return: ~ Dictionary containing statusline information, with these @@ -1562,18 +1573,46 @@ nvim_set_current_win({window}) *nvim_set_current_win()* nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* Sets a highlight group. - Note: Unlike the `:highlight` command which can update a - highlight group, this function completely replaces the - definition. For example: `nvim_set_hl(0, 'Visual', {})` will - clear the highlight group 'Visual'. + Note: + Unlike the `:highlight` command which can update a + highlight group, this function completely replaces the + definition. For example: `nvim_set_hl(0, 'Visual', {})` + will clear the highlight group 'Visual'. + + Note: + The fg and bg keys also accept the string values `"fg"` or + `"bg"` which act as aliases to the corresponding + foreground and background values of the Normal group. If + the Normal group has not been defined, using these values + results in an error. Parameters: ~ {ns_id} Namespace id for this highlight |nvim_create_namespace()|. Use 0 to set a highlight group globally |:highlight|. {name} Highlight group name, e.g. "ErrorMsg" - {val} Highlight definition map, like |synIDattr()|. In - addition, the following keys are recognized: + {val} Highlight definition map, accepts the following + keys: + • fg (or foreground): color name or "#RRGGBB", + see note. + • bg (or background): color name or "#RRGGBB", + see note. + • sp (or special): color name or "#RRGGBB" + • blend: integer between 0 and 100 + • bold: boolean + • standout: boolean + • underline: boolean + • underlineline: boolean + • undercurl: boolean + • underdot: boolean + • underdash: boolean + • strikethrough: boolean + • italic: boolean + • reverse: boolean + • nocombine: boolean + • link: name of another highlight group to link + to, see |:hi-link|. Additionally, the following + keys are recognized: • default: Don't override existing definition |:hi-default| • ctermfg: Sets foreground of cterm color @@ -1581,8 +1620,9 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* • ctermbg: Sets background of cterm color |highlight-ctermbg| • cterm: cterm attribute map, like - |highlight-args|. Note: Attributes default to - those set for `gui` if not set. + |highlight-args|. If not set, cterm attributes + will match those from the attribute map + documented above. nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. @@ -1607,13 +1647,15 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* for |:map|. {lhs} Left-hand-side |{lhs}| of the mapping. {rhs} Right-hand-side |{rhs}| of the mapping. - {opts} Optional parameters map. Accepts all - |:map-arguments| as keys excluding |<buffer>| but - including |noremap| and "desc". "desc" can be used - to give a description to keymap. When called from - Lua, also accepts a "callback" key that takes a - Lua function to call when the mapping is executed. - Values are Booleans. Unknown key is an error. + {opts} Optional parameters map: keys are + |:map-arguments|, values are booleans (default + false). Accepts all |:map-arguments| as keys + excluding |<buffer>| but including |noremap| and + "desc". Unknown key is an error. "desc" can be + used to give a description to the mapping. When + called from Lua, also accepts a "callback" key + that takes a Lua function to call when the mapping + is executed. nvim_set_option({name}, {value}) *nvim_set_option()* Sets the global value of an option. @@ -1686,8 +1728,7 @@ Vimscript Functions *api-vimscript* nvim_call_dict_function({dict}, {fn}, {args}) Calls a VimL |Dictionary-function| with the given arguments. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {dict} Dictionary, or String evaluating to a VimL |self| @@ -1701,8 +1742,7 @@ nvim_call_dict_function({dict}, {fn}, {args}) nvim_call_function({fn}, {args}) *nvim_call_function()* Calls a VimL function with the given arguments. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {fn} Function to call @@ -1711,24 +1751,56 @@ nvim_call_function({fn}, {args}) *nvim_call_function()* Return: ~ Result of the function call -nvim_command({command}) *nvim_command()* - Executes an ex-command. +nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* + Executes an Ex command. - On execution error: fails with VimL error, does not update - v:errmsg. + Unlike |nvim_command()| this command takes a structured + Dictionary instead of a String. This allows for easier + construction and manipulation of an Ex command. This also + allows for things such as having spaces inside a command + argument, expanding filenames in a command that otherwise + doesn't expand filenames, etc. + + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ - {command} Ex-command string + {cmd} Command to execute. Must be a Dictionary that can + contain the same values as the return value of + |nvim_parse_cmd()| except "addr", "nargs" and + "nextcmd" which are ignored if provided. All + values except for "cmd" are optional. + {opts} Optional parameters. + • output: (boolean, default false) Whether to + return command output. + + Return: ~ + Command output (non-error, non-shell |:!|) if `output` is + true, else empty string. See also: ~ |nvim_exec()| + |nvim_command()| + +nvim_command({command}) *nvim_command()* + Executes an Ex command. + + On execution error: fails with VimL error, updates v:errmsg. + + Prefer using |nvim_cmd()| or |nvim_exec()| over this. To + evaluate multiple lines of Vim script or an Ex command + directly, use |nvim_exec()|. To construct an Ex command using + a structured format and then execute it, use |nvim_cmd()|. To + modify an Ex command before evaluating it, use + |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. + + Parameters: ~ + {command} Ex command string nvim_eval({expr}) *nvim_eval()* Evaluates a VimL |expression|. Dictionaries and Lists are recursively expanded. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {expr} VimL expression string @@ -1737,14 +1809,13 @@ nvim_eval({expr}) *nvim_eval()* Evaluation result or expanded object nvim_exec({src}, {output}) *nvim_exec()* - Executes Vimscript (multiline block of Ex-commands), like + Executes Vimscript (multiline block of Ex commands), like anonymous |:source|. Unlike |nvim_command()| this function supports heredocs, script-scope (s:), etc. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ {src} Vimscript code @@ -1758,6 +1829,7 @@ nvim_exec({src}, {output}) *nvim_exec()* See also: ~ |execute()| |nvim_command()| + |nvim_cmd()| nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* Parse command line. @@ -2197,7 +2269,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start} First line index - {end} Last line index (exclusive) + {end} Last line index, exclusive {strict_indexing} Whether out-of-bounds should be an error. @@ -2268,16 +2340,18 @@ nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, This differs from |nvim_buf_get_lines()| in that it allows retrieving only portions of a line. - Indexing is zero-based. Column indices are end-exclusive. + Indexing is zero-based. Row indices are end-inclusive, and + column indices are end-exclusive. Prefer |nvim_buf_get_lines()| when retrieving entire lines. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start_row} First line index - {start_col} Starting byte offset of first line - {end_row} Last line index - {end_col} Ending byte offset of last line (exclusive) + {start_col} Starting column (byte offset) on first line + {end_row} Last line index, inclusive + {end_col} Ending column (byte offset) on last line, + exclusive {opts} Optional parameters. Currently unused. Return: ~ @@ -2357,7 +2431,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start} First line index - {end} Last line index (exclusive) + {end} Last line index, exclusive {strict_indexing} Whether out-of-bounds should be an error. {replacement} Array of lines to use as replacement @@ -2407,25 +2481,27 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, {replacement}) Sets (replaces) a range in the buffer - This is recommended over nvim_buf_set_lines when only + This is recommended over |nvim_buf_set_lines()| when only modifying parts of a line, as extmarks will be preserved on non-modified parts of the touched lines. - Indexing is zero-based and end-exclusive. + Indexing is zero-based. Row indices are end-inclusive, and + column indices are end-exclusive. - To insert text at a given index, set `start` and `end` ranges - to the same index. To delete a range, set `replacement` to an - array containing an empty string, or simply an empty array. + To insert text at a given `(row, column)` location, use + `start_row = end_row = row` and `start_col = end_col = col`. + To delete the text in a range, use `replacement = {}`. - Prefer nvim_buf_set_lines when adding or deleting entire lines - only. + Prefer |nvim_buf_set_lines()| if you are only adding or + deleting entire lines. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start_row} First line index - {start_col} First column - {end_row} Last line index - {end_col} Last column + {start_col} Starting column (byte offset) on first line + {end_row} Last line index, inclusive + {end_col} Ending column (byte offset) on last line, + exclusive {replacement} Array of lines to use as replacement nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* @@ -3393,6 +3469,8 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* • buf: (number) the expanded value of |<abuf>| • file: (string) the expanded value of |<afile>| + • data: (any) arbitrary data passed to + |nvim_exec_autocmds()| • command (string) optional: Vim command to execute on event. Cannot be used with @@ -3468,6 +3546,9 @@ nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* • modeline (bool) optional: defaults to true. Process the modeline after the autocommands |<nomodeline>|. + • data (any): arbitrary data to send to the + autocommand callback. See + |nvim_create_autocmd()| for details. See also: ~ |:doautocmd| diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index b9954dc99c..d197a2c62c 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -2800,7 +2800,7 @@ getcmdcompltype() *getcmdcompltype()* Return the type of the current command-line completion. Only works when the command line is being edited, thus requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. - See |command-completion| for the return string. + See |:command-completion| for the return string. Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|. Returns an empty string when completion is not defined. @@ -4976,10 +4976,9 @@ matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* The optional {dict} argument always supports the following items: - matchseq When this item is present and {str} contains - multiple words separated by white space, then - returns only matches that contain the words in - the given sequence. + matchseq When this item is present return only matches + that contain the characters in {str} in the + given sequence. If {list} is a list of dictionaries, then the optional {dict} argument supports the following additional items: @@ -7466,14 +7465,17 @@ stdpath({what}) *stdpath()* *E6100* directories. {what} Type Description ~ - cache String Cache directory. Arbitrary temporary + cache String Cache directory: arbitrary temporary storage for plugins, etc. - config String User configuration directory. The - |init.vim| is stored here. - config_dirs List Additional configuration directories. + config String User configuration directory. |init.vim| + is stored here. + config_dirs List Other configuration directories. data String User data directory. The |shada-file| is stored here. - data_dirs List Additional data directories. + data_dirs List Other data directories. + log String Logs directory (for use by plugins too). + state String Session state directory: storage for file + drafts, undo history, shada, etc. Example: > :echo stdpath("config") diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 13644cf208..e328bd28b5 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -106,11 +106,13 @@ internally and are no longer exposed as part of the API. Instead, use *vim.lsp.diagnostic.set_underline()* *vim.lsp.diagnostic.set_virtual_text()* -LSP Utility Functions ~ +LSP Functions ~ *vim.lsp.util.diagnostics_to_items()* Use |vim.diagnostic.toqflist()| instead. *vim.lsp.util.set_qflist()* Use |setqflist()| instead. *vim.lsp.util.set_loclist()* Use |setloclist()| instead. +*vim.lsp.buf_get_clients()* Use |vim.lsp.get_active_clients()| with + {buffer = bufnr} instead. Lua ~ *vim.register_keystroke_callback()* Use |vim.on_key()| instead. diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt index 82f279e781..6f0b862d3f 100644 --- a/runtime/doc/dev_style.txt +++ b/runtime/doc/dev_style.txt @@ -48,22 +48,6 @@ The format of the symbol name should be `NVIM_<DIRECTORY>_<FILE>_H`. < -Names and Order of Includes ~ - -Use standard order for readability and to avoid hidden dependencies: C -library, other libraries' `.h`, your project's `.h`. - - In foo.c order your includes as follows: - - 1. C system files. - 2. Other libraries' `.h` files. - 3. Your project's `.h` files. - - Exception: sometimes, system-specific code needs conditional includes. - Such code can put conditional includes after other includes. Of course, - keep your system-specific code small and localized. - - Constants ~ Do not use macros to define constants in headers. @@ -787,15 +771,6 @@ getting used to, but it is important that all project contributors follow the style rules so that they can all read and understand everyone's code easily. -Line Length ~ - -Each line of text in your code should be at most 100 characters long. - -Exception: if a comment line contains an example command or a literal URL -longer than 100 characters, that line may be longer than 100 characters for ease -of cut and paste. - - Non-ASCII Characters ~ Non-ASCII characters should be rare, and must use UTF-8 formatting. diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 32936a7ee6..2446506dec 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -336,8 +336,8 @@ config({opts}, {namespace}) *vim.diagnostic.config()* that returns any of the above. Parameters: ~ - {opts} table|nil When omitted or "nil", retrieve the - current configuration. Otherwise, a + {opts} (table|nil) When omitted or "nil", retrieve + the current configuration. Otherwise, a configuration table with the following keys: • underline: (default true) Use underline for diagnostics. Options: @@ -401,7 +401,7 @@ config({opts}, {namespace}) *vim.diagnostic.config()* displayed before lower severities (e.g. ERROR is displayed before WARN). Options: • reverse: (boolean) Reverse sort order - {namespace} number|nil Update the options for the given + {namespace} (number|nil) Update the options for the given namespace. When omitted, update the global diagnostic options. @@ -409,28 +409,28 @@ disable({bufnr}, {namespace}) *vim.diagnostic.disable()* Disable diagnostics in the given buffer. Parameters: ~ - {bufnr} number|nil Buffer number, or 0 for current + {bufnr} (number|nil) Buffer number, or 0 for current buffer. When omitted, disable diagnostics in all buffers. - {namespace} number|nil Only disable diagnostics for the + {namespace} (number|nil) Only disable diagnostics for the given namespace. enable({bufnr}, {namespace}) *vim.diagnostic.enable()* Enable diagnostics in the given buffer. Parameters: ~ - {bufnr} number|nil Buffer number, or 0 for current + {bufnr} (number|nil) Buffer number, or 0 for current buffer. When omitted, enable diagnostics in all buffers. - {namespace} number|nil Only enable diagnostics for the + {namespace} (number|nil) Only enable diagnostics for the given namespace. fromqflist({list}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. Parameters: ~ - {list} table A list of quickfix items from |getqflist()| - or |getloclist()|. + {list} (table) A list of quickfix items from + |getqflist()| or |getloclist()|. Return: ~ array of diagnostics |diagnostic-structure| @@ -439,9 +439,10 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* Get current diagnostics. Parameters: ~ - {bufnr} number|nil Buffer number to get diagnostics from. - Use 0 for current buffer or nil for all buffers. - {opts} table|nil A table with the following keys: + {bufnr} (number|nil) Buffer number to get diagnostics + from. Use 0 for current buffer or nil for all + buffers. + {opts} (table|nil) A table with the following keys: • namespace: (number) Limit diagnostics to the given namespace. • lnum: (number) Limit diagnostics to the given @@ -449,67 +450,68 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* • severity: See |diagnostic-severity|. Return: ~ - table A list of diagnostic items |diagnostic-structure|. + (table) A list of diagnostic items |diagnostic-structure|. get_namespace({namespace}) *vim.diagnostic.get_namespace()* Get namespace metadata. Parameters: ~ - {namespace} number Diagnostic namespace + {namespace} (number) Diagnostic namespace Return: ~ - table Namespace metadata + (table) Namespace metadata get_namespaces() *vim.diagnostic.get_namespaces()* Get current diagnostic namespaces. Return: ~ - table A list of active diagnostic namespaces + (table) A list of active diagnostic namespaces |vim.diagnostic|. get_next({opts}) *vim.diagnostic.get_next()* Get the next diagnostic closest to the cursor position. Parameters: ~ - {opts} table See |vim.diagnostic.goto_next()| + {opts} (table) See |vim.diagnostic.goto_next()| Return: ~ - table Next diagnostic + (table) Next diagnostic get_next_pos({opts}) *vim.diagnostic.get_next_pos()* Return the position of the next diagnostic in the current buffer. Parameters: ~ - {opts} table See |vim.diagnostic.goto_next()| + {opts} (table) See |vim.diagnostic.goto_next()| Return: ~ - table Next diagnostic position as a (row, col) tuple. + (table) Next diagnostic position as a (row, col) tuple. get_prev({opts}) *vim.diagnostic.get_prev()* Get the previous diagnostic closest to the cursor position. Parameters: ~ - {opts} table See |vim.diagnostic.goto_next()| + {opts} (table) See |vim.diagnostic.goto_next()| Return: ~ - table Previous diagnostic + (table) Previous diagnostic get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()* Return the position of the previous diagnostic in the current buffer. Parameters: ~ - {opts} table See |vim.diagnostic.goto_next()| + {opts} (table) See |vim.diagnostic.goto_next()| Return: ~ - table Previous diagnostic position as a (row, col) tuple. + (table) Previous diagnostic position as a (row, col) + tuple. goto_next({opts}) *vim.diagnostic.goto_next()* Move to the next diagnostic. Parameters: ~ - {opts} table|nil Configuration table with the following + {opts} (table|nil) Configuration table with the following keys: • namespace: (number) Only consider diagnostics from the given namespace. @@ -533,7 +535,7 @@ goto_prev({opts}) *vim.diagnostic.goto_prev()* Move to the previous diagnostic in the current buffer. Parameters: ~ - {opts} table See |vim.diagnostic.goto_next()| + {opts} (table) See |vim.diagnostic.goto_next()| hide({namespace}, {bufnr}) *vim.diagnostic.hide()* Hide currently displayed diagnostics. @@ -547,10 +549,10 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* |vim.diagnostic.disable()|. Parameters: ~ - {namespace} number|nil Diagnostic namespace. When + {namespace} (number|nil) Diagnostic namespace. When omitted, hide diagnostics from all namespaces. - {bufnr} number|nil Buffer number, or 0 for current + {bufnr} (number|nil) Buffer number, or 0 for current buffer. When omitted, hide diagnostics in all buffers. @@ -573,16 +575,16 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) < Parameters: ~ - {str} string String to parse diagnostics from. - {pat} string Lua pattern with capture groups. - {groups} table List of fields in a + {str} (string) String to parse diagnostics from. + {pat} (string) Lua pattern with capture groups. + {groups} (table) List of fields in a |diagnostic-structure| to associate with captures from {pat}. - {severity_map} table A table mapping the severity field + {severity_map} (table) A table mapping the severity field from {groups} with an item from |vim.diagnostic.severity|. - {defaults} table|nil Table of default values for any - fields not listed in {groups}. When + {defaults} (table|nil) Table of default values for + any fields not listed in {groups}. When omitted, numeric values default to 0 and "severity" defaults to ERROR. @@ -594,7 +596,7 @@ open_float({opts}, {...}) *vim.diagnostic.open_float()* Show diagnostics in a floating window. Parameters: ~ - {opts} table|nil Configuration table with the same keys + {opts} (table|nil) Configuration table with the same keys as |vim.lsp.util.open_floating_preview()| in addition to the following: • bufnr: (number) Buffer number to show @@ -665,10 +667,10 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()* |vim.diagnostic.hide()|. Parameters: ~ - {namespace} number|nil Diagnostic namespace. When + {namespace} (number|nil) Diagnostic namespace. When omitted, remove diagnostics from all namespaces. - {bufnr} number|nil Remove diagnostics for the given + {bufnr} (number|nil) Remove diagnostics for the given buffer. When omitted, diagnostics are removed for all buffers. @@ -676,18 +678,18 @@ set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* Set diagnostics for the given namespace and buffer. Parameters: ~ - {namespace} number The diagnostic namespace - {bufnr} number Buffer number - {diagnostics} table A list of diagnostic items + {namespace} (number) The diagnostic namespace + {bufnr} (number) Buffer number + {diagnostics} (table) A list of diagnostic items |diagnostic-structure| - {opts} table|nil Display options to pass to + {opts} (table|nil) Display options to pass to |vim.diagnostic.show()| setloclist({opts}) *vim.diagnostic.setloclist()* Add buffer diagnostics to the location list. Parameters: ~ - {opts} table|nil Configuration table with the following + {opts} (table|nil) Configuration table with the following keys: • namespace: (number) Only add diagnostics from the given namespace. @@ -703,7 +705,7 @@ setqflist({opts}) *vim.diagnostic.setqflist()* Add all diagnostics to the quickfix list. Parameters: ~ - {opts} table|nil Configuration table with the following + {opts} (table|nil) Configuration table with the following keys: • namespace: (number) Only add diagnostics from the given namespace. @@ -718,20 +720,20 @@ show({namespace}, {bufnr}, {diagnostics}, {opts}) Display diagnostics for the given namespace and buffer. Parameters: ~ - {namespace} number|nil Diagnostic namespace. When + {namespace} (number|nil) Diagnostic namespace. When omitted, show diagnostics from all namespaces. - {bufnr} number|nil Buffer number, or 0 for current - buffer. When omitted, show diagnostics in - all buffers. - {diagnostics} table|nil The diagnostics to display. When - omitted, use the saved diagnostics for the - given namespace and buffer. This can be + {bufnr} (number|nil) Buffer number, or 0 for + current buffer. When omitted, show + diagnostics in all buffers. + {diagnostics} (table|nil) The diagnostics to display. + When omitted, use the saved diagnostics for + the given namespace and buffer. This can be used to display a list of diagnostics without saving them or to display only a subset of diagnostics. May not be used when {namespace} or {bufnr} is nil. - {opts} table|nil Display options. See + {opts} (table|nil) Display options. See |vim.diagnostic.config()|. toqflist({diagnostics}) *vim.diagnostic.toqflist()* @@ -739,7 +741,7 @@ toqflist({diagnostics}) *vim.diagnostic.toqflist()* can be passed to |setqflist()| or |setloclist()|. Parameters: ~ - {diagnostics} table List of diagnostics + {diagnostics} (table) List of diagnostics |diagnostic-structure|. Return: ~ diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 63a5b69070..d1686741b4 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -3137,10 +3137,13 @@ text... :for {var} in {object} *:for* *E690* *E732* :endfo[r] *:endfo* *:endfor* Repeat the commands between `:for` and `:endfor` for - each item in {object}. {object} can be a |List| or - a |Blob|. Variable {var} is set to the value of each - item. When an error is detected for a command inside - the loop, execution continues after the `endfor`. + each item in {object}. {object} can be a |List|, + a |Blob| or a |String|. + + Variable {var} is set to the value of each item. + + When an error is detected for a command inside the + loop, execution continues after the `endfor`. Changing {object} inside the loop affects what items are used. Make a copy if this is unwanted: > :for item in copy(mylist) diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 5c36eaf8e5..58d49b5843 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1501,8 +1501,9 @@ tag command action ~ |:recover| :rec[over] recover a file from a swap file |:redo| :red[o] redo one undone change |:redir| :redi[r] redirect messages to a file or register -|:redraw| :redr[aw] force a redraw of the display -|:redrawstatus| :redraws[tatus] force a redraw of the status line(s) +|:redraw| :redr[aw] force a redraw of the display +|:redrawstatus| :redraws[tatus] force a redraw of the status line(s) and + window bar(s) |:redrawtabline| :redrawt[abline] force a redraw of the tabline |:registers| :reg[isters] display the contents of registers |:resize| :res[ize] change current window height diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index c1726bcb23..af3189a393 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -461,6 +461,39 @@ LspSignatureActiveParameter ============================================================================== EVENTS *lsp-events* + *LspAttach* +After an LSP client attaches to a buffer. The |autocmd-pattern| is the +name of the buffer. When used from Lua, the client ID is passed to the +callback in the "data" table. Example: > + + vim.api.nvim_create_autocmd("LspAttach", { + callback = function(args) + local bufnr = args.buf + local client = vim.lsp.get_client_by_id(args.data.client_id) + if client.server_capabilities.completionProvider then + vim.bo[bufnr].omnifunc = "v:lua.vim.lsp.omnifunc" + end + if client.server_capabilities.definitionProvider then + vim.bo[bufnr].tagfunc = "v:lua.vim.lsp.tagfunc" + end + end, + }) +< + *LspDetach* +Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the +name of the buffer. When used from Lua, the client ID is passed to the +callback in the "data" table. Example: > + + vim.api.nvim_create_autocmd("LspDetach", { + callback = function(args) + local client = vim.lsp.get_client_by_id(args.data.client_id) + -- Do something with the client + vim.cmd("setlocal tagfunc< omnifunc<") + end, + }) +< +In addition, the following |User| |autocommands| are provided: + LspProgressUpdate *LspProgressUpdate* Upon receipt of a progress notification from the server. See |vim.lsp.util.get_progress_messages()|. @@ -495,16 +528,8 @@ buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()* notification. Parameters: ~ - {bufnr} number Buffer handle, or 0 for current - {client_id} number Client id - -buf_get_clients({bufnr}) *vim.lsp.buf_get_clients()* - Gets a map of client_id:client pairs for the given buffer, - where each value is a |vim.lsp.client| object. - - Parameters: ~ - {bufnr} (optional, number): Buffer handle, or 0 for - current + {bufnr} (number) Buffer handle, or 0 for current + {client_id} (number) Client id buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()* Checks if a buffer is attached for a particular client. @@ -668,11 +693,11 @@ for_each_buffer_client({bufnr}, {fn}) Invokes a function for each LSP client attached to a buffer. Parameters: ~ - {bufnr} number Buffer number - {fn} function Function to run on each client attached - to buffer {bufnr}. The function takes the client, - client ID, and buffer number as arguments. - Example: > + {bufnr} (number) Buffer number + {fn} (function) Function to run on each client + attached to buffer {bufnr}. The function takes + the client, client ID, and buffer number as + arguments. Example: > vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr) print(vim.inspect(client)) @@ -690,24 +715,35 @@ formatexpr({opts}) *vim.lsp.formatexpr()* 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})')`. Parameters: ~ - {opts} table options for customizing the formatting + {opts} (table) options for customizing the formatting expression which takes the following optional keys: • timeout_ms (default 500ms). The timeout period for the formatting request. -get_active_clients() *vim.lsp.get_active_clients()* - Gets all active clients. +get_active_clients({filter}) *vim.lsp.get_active_clients()* + Get active clients. + + Parameters: ~ + {filter} (table|nil) A table with key-value pairs used to + filter the returned clients. The available keys + are: + • id (number): Only return clients with the + given id + • bufnr (number): Only return clients attached + to this buffer + • name (string): Only return clients with the + given name Return: ~ - Table of |vim.lsp.client| objects + (table) List of |vim.lsp.client| objects *vim.lsp.get_buffers_by_client_id()* get_buffers_by_client_id({client_id}) Returns list of buffers attached to client_id. Parameters: ~ - {client_id} number client id + {client_id} (number) client id Return: ~ list of buffer ids @@ -717,7 +753,7 @@ get_client_by_id({client_id}) *vim.lsp.get_client_by_id()* client may not yet be fully initialized. Parameters: ~ - {client_id} number client id + {client_id} (number) client id Return: ~ |vim.lsp.client| object, or nil @@ -820,7 +856,7 @@ start_client({config}) *vim.lsp.start_client()* language server if requested via `workspace/configuration`. Keys are case-sensitive. - {commands} table Table that maps string of + {commands} (table) Table that maps string of clientside commands to user-defined functions. Commands passed to start_client take precedence over the @@ -908,10 +944,10 @@ start_client({config}) *vim.lsp.start_client()* kill -15. If set to false, nvim exits immediately after sending the 'shutdown' request to the server. - {root_dir} string Directory where the LSP server - will base its workspaceFolders, - rootUri, and rootPath on - initialization. + {root_dir} (string) Directory where the LSP + server will base its + workspaceFolders, rootUri, and + rootPath on initialization. Return: ~ Client id. |vim.lsp.get_client_by_id()| Note: client may @@ -935,7 +971,7 @@ stop_client({client_id}, {force}) *vim.lsp.stop_client()* Parameters: ~ {client_id} client id or |vim.lsp.client| object, or list thereof - {force} boolean (optional) shutdown forcefully + {force} (boolean) (optional) shutdown forcefully tagfunc({...}) *vim.lsp.tagfunc()* Provides an interface between the built-in client and @@ -980,15 +1016,15 @@ code_action({options}) *vim.lsp.buf.code_action()* position. Parameters: ~ - {options} table|nil Optional table which holds the + {options} (table|nil) Optional table which holds the following optional fields: • context (table|nil): Corresponds to `CodeActionContext` of the LSP specification: • diagnostics (table|nil): LSP`Diagnostic[]` . Inferred from the current position if not provided. - • only (string|nil): LSP `CodeActionKind` - used to filter the code actions. Most - language servers support values like - `refactor` or `quickfix`. + • only (table|nil): List of LSP + `CodeActionKind`s used to filter the code + actions. Most language servers support + values like `refactor` or `quickfix`. • filter (function|nil): Predicate function taking an `CodeAction` and returning a @@ -1015,15 +1051,25 @@ completion({context}) *vim.lsp.buf.completion()* See also: ~ |vim.lsp.protocol.constants.CompletionTriggerKind| -declaration() *vim.lsp.buf.declaration()* +declaration({options}) *vim.lsp.buf.declaration()* Jumps to the declaration of the symbol under the cursor. Note: Many servers do not implement this method. Generally, see |vim.lsp.buf.definition()| instead. -definition() *vim.lsp.buf.definition()* + Parameters: ~ + {options} (table|nil) additional options + • reuse_win: (boolean) Jump to existing window + if buffer is already open. + +definition({options}) *vim.lsp.buf.definition()* Jumps to the definition of the symbol under the cursor. + Parameters: ~ + {options} (table|nil) additional options + • reuse_win: (boolean) Jump to existing window + if buffer is already open. + document_highlight() *vim.lsp.buf.document_highlight()* Send request to the server to resolve document highlights for the current text document position. This request can be @@ -1048,7 +1094,7 @@ execute_command({command_params}) *vim.lsp.buf.execute_command()* Executes an LSP server command. Parameters: ~ - {command_params} table A valid `ExecuteCommandParams` + {command_params} (table) A valid `ExecuteCommandParams` object See also: ~ @@ -1146,7 +1192,7 @@ formatting_sync({options}, {timeout_ms}) < Parameters: ~ - {options} table|nil with valid `FormattingOptions` + {options} (table|nil) with valid `FormattingOptions` entries {timeout_ms} (number) Request timeout @@ -1180,13 +1226,13 @@ range_code_action({context}, {start_pos}, {end_pos}) Performs |vim.lsp.buf.code_action()| for a given range. Parameters: ~ - {context} table|nil `CodeActionContext` of the LSP specification: + {context} (table|nil) `CodeActionContext` of the LSP specification: • diagnostics: (table|nil) LSP`Diagnostic[]` . Inferred from the current position if not provided. - • only: (string|nil) LSP `CodeActionKind` - used to filter the code actions. Most - language servers support values like - `refactor` or `quickfix`. + • only: (table|nil) List of LSP + `CodeActionKind`s used to filter the code + actions. Most language servers support + values like `refactor` or `quickfix`. {start_pos} ({number, number}, optional) mark-indexed position. Defaults to the start of the last visual selection. @@ -1227,10 +1273,10 @@ rename({new_name}, {options}) *vim.lsp.buf.rename()* Renames all references to the symbol under the cursor. Parameters: ~ - {new_name} string|nil If not provided, the user will be + {new_name} (string|nil) If not provided, the user will be prompted for a new name using |vim.ui.input()|. - {options} table|nil additional options + {options} (table|nil) additional options • filter (function|nil): Predicate to filter clients used for rename. Receives the attached clients as argument and must return @@ -1250,10 +1296,15 @@ signature_help() *vim.lsp.buf.signature_help()* Displays signature information about the symbol under the cursor in a floating window. -type_definition() *vim.lsp.buf.type_definition()* +type_definition({options}) *vim.lsp.buf.type_definition()* Jumps to the definition of the type of the symbol under the cursor. + Parameters: ~ + {options} (table|nil) additional options + • reuse_win: (boolean) Jump to existing window + if buffer is already open. + workspace_symbol({query}) *vim.lsp.buf.workspace_symbol()* Lists all symbols in the current workspace in the quickfix window. @@ -1275,7 +1326,7 @@ get_namespace({client_id}) *vim.lsp.diagnostic.get_namespace()* |vim.diagnostic|. Parameters: ~ - {client_id} number The id of the LSP client + {client_id} (number) The id of the LSP client *vim.lsp.diagnostic.on_publish_diagnostics()* on_publish_diagnostics({_}, {result}, {ctx}, {config}) @@ -1305,7 +1356,7 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config}) < Parameters: ~ - {config} table Configuration table (see + {config} (table) Configuration table (see |vim.diagnostic.config()|). @@ -1316,20 +1367,20 @@ display({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.display()* Display the lenses using virtual text Parameters: ~ - {lenses} table of lenses to display (`CodeLens[] | + {lenses} (table) of lenses to display (`CodeLens[] | null`) - {bufnr} number - {client_id} number + {bufnr} (number) + {client_id} (number) get({bufnr}) *vim.lsp.codelens.get()* Return all lenses for the given buffer Parameters: ~ - {bufnr} number Buffer number. 0 can be used for the + {bufnr} (number) Buffer number. 0 can be used for the current buffer. Return: ~ - table (`CodeLens[]`) + (table) (`CodeLens[]`) *vim.lsp.codelens.on_codelens()* on_codelens({err}, {result}, {ctx}, {_}) @@ -1351,10 +1402,10 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()* Store lenses for a specific buffer and client Parameters: ~ - {lenses} table of lenses to store (`CodeLens[] | + {lenses} (table) of lenses to store (`CodeLens[] | null`) - {bufnr} number - {client_id} number + {bufnr} (number) + {client_id} (number) ============================================================================== @@ -1372,7 +1423,7 @@ hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()* < Parameters: ~ - {config} table Configuration table. + {config} (table) Configuration table. • border: (default=nil) • Add borders to the floating window • See |nvim_open_win()| @@ -1392,7 +1443,7 @@ signature_help({_}, {result}, {ctx}, {config}) < Parameters: ~ - {config} table Configuration table. + {config} (table) Configuration table. • border: (default=nil) • Add borders to the floating window • See |vim.api.nvim_open_win()| @@ -1420,9 +1471,9 @@ apply_text_edits({text_edits}, {bufnr}, {offset_encoding}) Applies a list of text edits to a buffer. Parameters: ~ - {text_edits} table list of `TextEdit` objects - {bufnr} number Buffer id - {offset_encoding} string utf-8|utf-16|utf-32 + {text_edits} (table) list of `TextEdit` objects + {bufnr} (number) Buffer id + {offset_encoding} (string) utf-8|utf-16|utf-32 See also: ~ https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit @@ -1432,24 +1483,24 @@ apply_workspace_edit({workspace_edit}, {offset_encoding}) Applies a `WorkspaceEdit`. Parameters: ~ - {workspace_edit} table `WorkspaceEdit` - {offset_encoding} string utf-8|utf-16|utf-32 (required) + {workspace_edit} (table) `WorkspaceEdit` + {offset_encoding} (string) utf-8|utf-16|utf-32 (required) buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()* Removes document highlights from a buffer. Parameters: ~ - {bufnr} number Buffer id + {bufnr} (number) Buffer id *vim.lsp.util.buf_highlight_references()* buf_highlight_references({bufnr}, {references}, {offset_encoding}) Shows a list of document highlights for a certain buffer. Parameters: ~ - {bufnr} number Buffer id - {references} table List of `DocumentHighlight` + {bufnr} (number) Buffer id + {references} (table) List of `DocumentHighlight` objects to highlight - {offset_encoding} string One of "utf-8", "utf-16", + {offset_encoding} (string) One of "utf-8", "utf-16", "utf-32". See also: ~ @@ -1464,9 +1515,9 @@ character_offset({buf}, {row}, {col}, {offset_encoding}) {buf} buffer id (0 for current) {row} 0-indexed line {col} 0-indexed byte offset in line - {offset_encoding} string utf-8|utf-16|utf-32|nil defaults - to `offset_encoding` of first client of - `buf` + {offset_encoding} (string) utf-8|utf-16|utf-32|nil + defaults to `offset_encoding` of first + client of `buf` Return: ~ (number, number) `offset_encoding` index of the character @@ -1539,12 +1590,14 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()* |shiftwidth| *vim.lsp.util.jump_to_location()* -jump_to_location({location}, {offset_encoding}) +jump_to_location({location}, {offset_encoding}, {reuse_win}) Jumps to a location. Parameters: ~ - {location} table (`Location`|`LocationLink`) - {offset_encoding} string utf-8|utf-16|utf-32 (required) + {location} (table) (`Location`|`LocationLink`) + {offset_encoding} (string) utf-8|utf-16|utf-32 (required) + {reuse_win} (boolean) Jump to existing window if + buffer is already opened. Return: ~ `true` if the jump succeeded @@ -1559,9 +1612,9 @@ locations_to_items({locations}, {offset_encoding}) |setqflist()| or |setloclist()|. Parameters: ~ - {locations} table list of `Location`s or + {locations} (table) list of `Location`s or `LocationLink`s - {offset_encoding} string offset_encoding for locations + {offset_encoding} (string) offset_encoding for locations utf-8|utf-16|utf-32 Return: ~ @@ -1606,7 +1659,7 @@ make_formatting_params({options}) buffer and cursor position. Parameters: ~ - {options} table|nil with valid `FormattingOptions` + {options} (table|nil) with valid `FormattingOptions` entries Return: ~ @@ -1629,9 +1682,9 @@ make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding}) end of the last visual selection. {bufnr} (optional, number): buffer handle or 0 for current, defaults to current - {offset_encoding} string utf-8|utf-16|utf-32|nil defaults - to `offset_encoding` of first client of - `bufnr` + {offset_encoding} (string) utf-8|utf-16|utf-32|nil + defaults to `offset_encoding` of first + client of `bufnr` Return: ~ { textDocument = { uri = `current_file_uri` }, range = { @@ -1645,9 +1698,9 @@ make_position_params({window}, {offset_encoding}) Parameters: ~ {window} (optional, number): window handle or 0 for current, defaults to current - {offset_encoding} string utf-8|utf-16|utf-32|nil defaults - to `offset_encoding` of first client of - buffer of `window` + {offset_encoding} (string) utf-8|utf-16|utf-32|nil + defaults to `offset_encoding` of first + client of buffer of `window` Return: ~ `TextDocumentPositionParams` object @@ -1666,9 +1719,9 @@ make_range_params({window}, {offset_encoding}) Parameters: ~ {window} (optional, number): window handle or 0 for current, defaults to current - {offset_encoding} string utf-8|utf-16|utf-32|nil defaults - to `offset_encoding` of first client of - buffer of `window` + {offset_encoding} (string) utf-8|utf-16|utf-32|nil + defaults to `offset_encoding` of first + client of buffer of `window` Return: ~ { textDocument = { uri = `current_file_uri` }, range = { @@ -1702,9 +1755,9 @@ open_floating_preview({contents}, {syntax}, {opts}) Shows contents in a floating window. Parameters: ~ - {contents} table of lines to show in window - {syntax} string of syntax to set for opened buffer - {opts} table with optional fields (additional keys + {contents} (table) of lines to show in window + {syntax} (string) of syntax to set for opened buffer + {opts} (table) with optional fields (additional keys are passed on to |vim.api.nvim_open_win()|) • height: (number) height of floating window • width: (number) width of floating window @@ -1739,10 +1792,10 @@ parse_snippet({input}) *vim.lsp.util.parse_snippet()* Parses snippets in a completion entry. Parameters: ~ - {input} string unparsed snippet + {input} (string) unparsed snippet Return: ~ - string parsed snippet + (string) parsed snippet preview_location({location}, {opts}) *vim.lsp.util.preview_location()* Previews a location in a floating window @@ -1795,7 +1848,7 @@ stylize_markdown({bufnr}, {contents}, {opts}) `open_floating_preview` instead Parameters: ~ - {contents} table of lines to show in window + {contents} (table) of lines to show in window {opts} dictionary with optional fields • height of floating window • width of floating window @@ -1873,14 +1926,15 @@ get_level() *vim.lsp.log.get_level()* Gets the current log level. Return: ~ - string current log level + (string) current log level set_format_func({handle}) *vim.lsp.log.set_format_func()* Sets formatting function used to format logs Parameters: ~ - {handle} function function to apply to logging arguments, - pass vim.inspect for multi-line formatting + {handle} (function) function to apply to logging + arguments, pass vim.inspect for multi-line + formatting set_level({level}) *vim.lsp.log.set_level()* Sets the current log level. @@ -1892,7 +1946,7 @@ should_log({level}) *vim.lsp.log.should_log()* Checks whether the level is sufficient for logging. Parameters: ~ - {level} number log level + {level} (number) log level Return: ~ (bool) true if would log, false if not @@ -1998,19 +2052,19 @@ compute_diff({prev_lines}, {curr_lines}, {firstline}, {lastline}, curr lines Parameters: ~ - {prev_lines} table list of lines - {curr_lines} table list of lines - {firstline} number line to begin search for first + {prev_lines} (table) list of lines + {curr_lines} (table) list of lines + {firstline} (number) line to begin search for first difference - {lastline} number line to begin search in + {lastline} (number) line to begin search in old_lines for last difference - {new_lastline} number line to begin search in + {new_lastline} (number) line to begin search in new_lines for last difference - {offset_encoding} string encoding requested by language + {offset_encoding} (string) encoding requested by language server Return: ~ - table TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocumentContentChangeEvent + (table) TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocumentContentChangeEvent ============================================================================== @@ -2027,10 +2081,10 @@ resolve_capabilities({server_capabilities}) capabilities. Parameters: ~ - {server_capabilities} table Table of capabilities + {server_capabilities} (table) Table of capabilities supported by the server Return: ~ - table Normalized table of capabilities + (table) Normalized table of capabilities vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 534a40ff4f..b551552c03 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -4,52 +4,52 @@ NVIM REFERENCE MANUAL -Lua engine *lua* *Lua* +Lua engine *lua* *Lua* - Type |gO| to see the table of contents. + Type |gO| to see the table of contents. ============================================================================== -INTRODUCTION *lua-intro* +INTRODUCTION *lua-intro* -The Lua 5.1 language is builtin and always available. Try this command to get +The Lua 5.1 language is builtin and always available. Try this command to get an idea of what lurks beneath: > :lua print(vim.inspect(package.loaded)) - -Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the +< +Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the "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. The |:source| and |:runtime| commands can run Lua scripts as well as Vim -scripts. Lua modules can be loaded with `require('name')`, which +scripts. Lua modules can be loaded with `require('name')`, which conventionally returns a table but can return any value. See |lua-require| for details on how Nvim finds and loads Lua modules. See |lua-require-example| for an example of how to write and use a module. ============================================================================== -IMPORTING LUA MODULES *lua-require* +IMPORTING LUA MODULES *lua-require* Modules are searched for under the directories specified in 'runtimepath', in -the order they appear. Any `.` in the module name is treated as a directory -separator when searching. For a module `foo.bar`, each directory is searched -for `lua/foo/bar.lua`, then `lua/foo/bar/init.lua`. If no files are found, +the order they appear. Any `.` in the module name is treated as a directory +separator when searching. For a module `foo.bar`, each directory is searched +for `lua/foo/bar.lua`, then `lua/foo/bar/init.lua`. If no files are found, the directories are searched again for a shared library with a name matching -`lua/foo/bar.?`, where `?` is a list of suffixes (such as `so` or `dll`) -derived from the initial value of `package.cpath`. If still no files are -found, Nvim falls back to Lua's default search mechanism. The first script -found is run and `require()` returns the value returned by the script if any, -else `true`. - -The return value is cached after the first call to `require()` for each -module, with subsequent calls returning the cached value without searching for -or executing any script. For further details on `require()`, see the Lua +`lua/foo/bar.?`, where `?` is a list of suffixes (such as `so` or `dll`) derived from +the initial value of `package.cpath`. If still no files are found, Nvim falls +back to Lua's default search mechanism. The first script found is run and +`require()` returns the value returned by the script if any, else `true`. + +The return value is cached after the first call to `require()` for each module, +with subsequent calls returning the cached value without searching for, or +executing any script. For further details on `require()`, see the Lua documentation at https://www.lua.org/manual/5.1/manual.html#pdf-require. For example, if 'runtimepath' is `foo,bar` and `package.cpath` was `./?.so;./?.dll` at startup, `require('mod')` searches these paths in order and loads the first module found: + foo/lua/mod.lua foo/lua/mod/init.lua bar/lua/mod.lua @@ -59,35 +59,34 @@ and loads the first module found: bar/lua/mod.so bar/lua/mod.dll - *lua-package-path* -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 +Nvim automatically adjusts `package.path` and `package.cpath` according to the +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 +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: +the existing `package.cpath` are used. Example: 1. Given that - 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`; - - initial (defined at compile-time or derived from - `$LUA_CPATH`/`$LUA_INIT`) `package.cpath` contains + - initial (defined at compile-time or derived from + `$LUA_CPATH`/`$LUA_INIT`) `package.cpath` contains `./?.so;/def/ghi/a?d/j/g.elf;/def/?.so`. -2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in - order: parts of the path starting from the first path component containing +2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in + order: parts of the path starting from the first path component containing question mark and preceding path separator. -3. The suffix of `/def/?.so`, namely `/?.so` is not unique, as it’s the same - as the suffix of the first path from `package.path` (i.e. `./?.so`). Which +3. The suffix of `/def/?.so`, namely `/?.so` is not unique, as it’s the same + as the suffix of the first path from `package.path` (i.e. `./?.so`). Which leaves `/?.so` and `/a?d/j/g.elf`, in this order. -4. 'runtimepath' has three paths: `/foo/bar`, `/xxx;yyy/baz` and `/abc`. The - second one contains semicolon which is a paths separator so it is out, +4. 'runtimepath' has three paths: `/foo/bar`, `/xxx;yyy/baz` and `/abc`. The + second one contains a semicolon which is a paths separator so it is out, leaving only `/foo/bar` and `/abc`, in order. -5. The cartesian product of paths from 4. and suffixes from 3. is taken, - giving four variants. In each variant `/lua` path segment is inserted - between path and suffix, leaving +5. The cartesian product of paths from 4. and suffixes from 3. is taken, + giving four variants. In each variant, a `/lua` path segment is inserted + between path and suffix, leaving: - `/foo/bar/lua/?.so` - `/foo/bar/lua/a?d/j/g.elf` @@ -107,28 +106,28 @@ Note: - To track 'runtimepath' updates, paths added at previous update are remembered and removed at the next update, while all paths derived from the - new 'runtimepath' are prepended as described above. This allows removing + new 'runtimepath' are prepended as described above. This allows removing paths when path is removed from 'runtimepath', adding paths when they are added and reordering `package.path`/`package.cpath` content if 'runtimepath' was reordered. - Although adjustments happen automatically, Nvim does not track current - values of `package.path` or `package.cpath`. If you happen to delete some + values of `package.path` or `package.cpath`. If you happen to delete some paths from there you can set 'runtimepath' to trigger an update: > let &runtimepath = &runtimepath - Skipping paths from 'runtimepath' which contain semicolons applies both to - `package.path` and `package.cpath`. Given that there are some badly written - plugins using shell which will not work with paths containing semicolons it - is better to not have them in 'runtimepath' at all. + `package.path` and `package.cpath`. Given that there are some badly written + plugins using shell, which will not work with paths containing semicolons, + it is better to not have them in 'runtimepath' at all. ============================================================================== -Lua Syntax Information *lua-syntax-help* +Lua Syntax Information *lua-syntax-help* While Lua has a simple syntax, there are a few things to understand, particularly when looking at the documentation above. - *lua-syntax-call-function* + *lua-syntax-call-function* Lua functions can be called in multiple ways. Consider the function: > @@ -136,8 +135,7 @@ Lua functions can be called in multiple ways. Consider the function: > print("A is: ", a) print("B is: ", b) end - - +< The first way to call this function is: > example_func(1, 2) @@ -154,7 +152,6 @@ not supplied are automatically set to `nil`. For example: > -- A is: 1 -- B is: nil < - Additionally, if any extra parameters are passed, they are discarded completely. @@ -172,18 +169,16 @@ single dictionary, for example: > func_with_opts { foo = true, filename = "hello.world" } < - In this style, each "parameter" is passed via keyword. It is still valid to call the function in the standard style: > func_with_opts({ foo = true, filename = "hello.world" }) < - But often in the documentation, you will see the former rather than the latter style due to its brevity. ============================================================================== -Lua Patterns *lua-patterns* +Lua Patterns *lua-patterns* For performance reasons, Lua does not support regular expressions natively. Instead, the Lua `string` standard library allows manipulations using a @@ -207,13 +202,13 @@ For more complex matching, Vim regular expressions can be used from Lua through |vim.regex()|. ------------------------------------------------------------------------------ -LUA PLUGIN EXAMPLE *lua-require-example* +LUA PLUGIN EXAMPLE *lua-require-example* -The following example plugin adds a command `:MakeCharBlob` which transforms -current buffer into a long `unsigned char` array. Lua contains transformation -function in a module `lua/charblob.lua` which is imported in -`autoload/charblob.vim` (`require("charblob")`). Example plugin is supposed -to be put into any directory from 'runtimepath', e.g. `~/.config/nvim` (in +The following example plugin adds a command `:MakeCharBlob` which transforms +current buffer into a long `unsigned char` array. Lua contains transformation +function in a module `lua/charblob.lua` which is imported in +`autoload/charblob.vim` (`require("charblob")`). Example plugin is supposed +to be put into any directory from 'runtimepath', e.g. `~/.config/nvim` (in this case `lua/charblob.lua` means `~/.config/nvim/lua/charblob.lua`). autoload/charblob.vim: > @@ -223,7 +218,7 @@ autoload/charblob.vim: > \ 'require("charblob").encode(unpack(_A))', \ [getline(1, '$'), &textwidth, ' '])) endfunction - +< plugin/charblob.vim: > if exists('g:charblob_loaded') @@ -232,7 +227,7 @@ plugin/charblob.vim: > let g:charblob_loaded = 1 command MakeCharBlob :call charblob#encode_buffer() - +< lua/charblob.lua: > local function charblob_bytes_iter(lines) @@ -282,9 +277,9 @@ lua/charblob.lua: > bytes_iter = charblob_bytes_iter, encode = charblob_encode, } - +< ============================================================================== -COMMANDS *lua-commands* +COMMANDS *lua-commands* These commands execute a Lua chunk from either the command line (:lua, :luado) or a file (:luafile) on the given line [range]. As always in Lua, each chunk @@ -295,10 +290,10 @@ command calls. The |lua-stdlib| modules, user modules, and anything else on The Lua print() function redirects its output to the Nvim message area, with arguments separated by " " (space) instead of "\t" (tab). - *:lua* + *:lua* :[range]lua {chunk} Executes Lua chunk {chunk}. - if {chunk} starts with "=" the rest of the chunk is + 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: > @@ -308,7 +303,7 @@ arguments separated by " " (space) instead of "\t" (tab). < To see the LuaJIT version: > :lua =jit.version < - *:lua-heredoc* + *:lua-heredoc* :[range]lua << [endmarker] {script} {endmarker} @@ -328,11 +323,11 @@ arguments separated by " " (space) instead of "\t" (tab). linenr, #curline)) EOF endfunction - -< Note that the `local` variables will disappear when +< + Note that the `local` variables will disappear when the block finishes. But not globals. - *:luado* + *:luado* :[range]luado {body} Executes Lua chunk "function(line, linenr) {body} end" for each buffer line in [range], where `line` is the current line text (without <EOL>), and `linenr` is the @@ -349,8 +344,7 @@ arguments separated by " " (space) instead of "\t" (tab). :lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" } :luado if bp:match(line) then return "-->\t" .. line end < - - *:luafile* + *:luafile* :[range]luafile {file} Execute Lua script in {file}. The whole argument is used as the filename (like @@ -363,19 +357,19 @@ arguments separated by " " (space) instead of "\t" (tab). < ============================================================================== -luaeval() *lua-eval* *luaeval()* +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: -> +"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 Vimscript types. If a Lua string contains a NUL byte, it will be converted to a |Blob|. Conversion of other Lua types is an error. @@ -387,22 +381,22 @@ Example: > 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 +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 +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 +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 + *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 @@ -425,14 +419,14 @@ Examples: > : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y}) : endfunction :echo Rand(1,10) - -Note: second argument to `luaeval` is converted ("marshalled") from Vimscript +< +Note: Second argument to `luaeval` is converted ("marshalled") from Vimscript to Lua, so changes to Lua containers do not affect values in Vimscript. Return value is also always converted. When converting, |msgpack-special-dict|s are treated specially. ============================================================================== -Vimscript v:lua interface *v:lua-call* +Vimscript v:lua interface *v:lua-call* From Vimscript the special `v:lua` prefix can be used to call Lua functions which are global or accessible from global tables. The expression > @@ -447,7 +441,7 @@ is equivalent to the Lua chunk > In addition, functions of packages can be accessed like > v:lua.require'mypack'.func(arg1, arg2) v:lua.require'mypack.submod'.func(arg1, arg2) -Note: only single quote form without parens is allowed. Using +Note: Only single quote form without parens is allowed. Using `require"mypack"` or `require('mypack')` as prefixes do NOT work (the latter is still valid as a function call of itself, in case require returns a useful value). @@ -455,7 +449,7 @@ value). The `v:lua` prefix may be used to call Lua functions as |method|s. For example: > arg1->v:lua.somemod.func(arg2) - +< You can use `v:lua` in "func" options like 'tagfunc', 'omnifunc', etc. For example consider the following Lua omnifunc handler: > @@ -468,7 +462,7 @@ For example consider the following Lua omnifunc handler: > end vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.mymod.omnifunc') -Note: the module ("mymod" in the above example) must either be a Lua global, +Note: The module ("mymod" in the above example) must either be a Lua global, or use the require syntax as specified above to access it from a package. Note: `v:lua` without a call is not allowed in a Vimscript expression: @@ -478,13 +472,12 @@ Note: `v:lua` without a call is not allowed in a Vimscript expression: call SomeFunc(v:lua.mycallback) " Error let g:foo = v:lua " Error let g:foo = v:['lua'] " Error - - +< ============================================================================== -Lua standard modules *lua-stdlib* +Lua standard modules *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") +various functions and sub-modules. It is always loaded, thus `require("vim")` is unnecessary. You can peek at the module properties: > @@ -515,34 +508,35 @@ Note that underscore-prefixed functions (e.g. "_os_proc_children") are internal/private and must not be used by plugins. ------------------------------------------------------------------------------ -VIM.LOOP *lua-loop* *vim.loop* +VIM.LOOP *lua-loop* *vim.loop* -`vim.loop` exposes all features of the Nvim event-loop. This is a low-level +`vim.loop` exposes all features of the Nvim event-loop. This is a low-level API that provides functionality for networking, filesystem, and process -management. Try this command to see available functions: > +management. Try this command to see available functions: > :lua print(vim.inspect(vim.loop)) - +< Reference: https://github.com/luvit/luv/blob/master/docs.md Examples: https://github.com/luvit/luv/tree/master/examples - *E5560* *lua-loop-callbacks* + *E5560* *lua-loop-callbacks* It is an error to directly invoke `vim.api` functions (except |api-fast|) in -`vim.loop` callbacks. For example, this is an error: > +`vim.loop` callbacks. For example, this is an error: > local timer = vim.loop.new_timer() timer:start(1000, 0, function() vim.api.nvim_command('echomsg "test"') end) - +< To avoid the error use |vim.schedule_wrap()| to defer the callback: > local timer = vim.loop.new_timer() timer:start(1000, 0, vim.schedule_wrap(function() vim.api.nvim_command('echomsg "test"') end)) - -(For one-shot timers, see |vim.defer_fn()|, which automatically adds the wrapping.) +< +(For one-shot timers, see |vim.defer_fn()|, which automatically adds the +wrapping.) Example: repeating timer 1. Save this code to a file. @@ -560,9 +554,8 @@ Example: repeating timer i = i + 1 end) print('sleeping'); - - -Example: File-change detection *watch-file* +< +Example: File-change detection *watch-file* 1. Save this code to a file. 2. Execute it with ":luafile %". 3. Use ":Watch %" to watch any file. @@ -586,9 +579,8 @@ Example: File-change detection *watch-file* end vim.api.nvim_command( "command! -nargs=1 Watch call luaeval('watch_file(_A)', expand('<args>'))") - - -Example: TCP echo-server *tcp-server* +< +Example: TCP echo-server *tcp-server* 1. Save this code to a file. 2. Execute it with ":luafile %". 3. Note the port number. @@ -616,9 +608,8 @@ Example: TCP echo-server *tcp-server* end) end) print('TCP echo-server listening on port: '..server:getsockname().port) - - -Multithreading *lua-loop-threading* +< +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 @@ -638,7 +629,7 @@ A subset of the `vim.*` API is available in threads. This includes: - `vim.is_thread()` returns true from a non-main thread. ------------------------------------------------------------------------------ -VIM.HIGHLIGHT *lua-highlight* +VIM.HIGHLIGHT *lua-highlight* Nvim includes a function for highlighting a selection on yank (see for example https://github.com/machakann/vim-highlightedyank). To enable it, add @@ -654,8 +645,7 @@ If you want to exclude visual selections from highlighting on yank, use > au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} < - -vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* +vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* Highlights the yanked text. The fields of the optional dict {opts} control the highlight: - {higroup} highlight group for yanked region (default |hl-IncSearch|) @@ -678,12 +668,12 @@ vim.highlight.range({bufnr}, {ns}, {hlgroup}, {start}, {finish}, {opts}) {opts} optional parameters: • `regtype`: type of range (characterwise, linewise, or blockwise, see |setreg|), default `'v'` - • `inclusive`: range includes end position, default - `false` + • `inclusive`: range includes end position, + default `false` • `priority`: priority of highlight, default `vim.highlight.user` (see below) -vim.highlight.priorities *vim.highlight.priorities* +vim.highlight.priorities *vim.highlight.priorities* Table with default priorities used for highlighting: • `syntax`: `50`, used for standard syntax highlighting @@ -693,19 +683,20 @@ vim.highlight.priorities *vim.highlight.priorities* document symbols or `on_yank` autocommands ------------------------------------------------------------------------------ -VIM.REGEX *lua-regex* +VIM.REGEX *lua-regex* Vim regexes can be used directly from lua. Currently they only allow matching within a single line. -vim.regex({re}) *vim.regex()* +vim.regex({re}) *vim.regex()* Parse the Vim regex {re} and return a regex object. Regexes are - "magic" and case-insensitive by default, regardless of 'magic' and - 'ignorecase'. The can be controlled with flags, see |/magic|. + "magic" and case-sensitive by default, regardless of 'magic' and + 'ignorecase'. They can be controlled with flags, see |/magic| and + |/ignorecase|. Methods on the regex object: -regex:match_str({str}) *regex:match_str()* +regex:match_str({str}) *regex:match_str()* Match the string against the regex. If the string should match the regex precisely, surround the regex with `^` and `$`. If the was a match, the byte indices for the beginning and end of @@ -713,7 +704,7 @@ regex:match_str({str}) *regex:match_str()* As any integer is truth-y, `regex:match()` can be directly used as a condition in an if-statement. -regex:match_line({bufnr}, {line_idx}[, {start}, {end}]) *regex:match_line()* +regex:match_line({bufnr}, {line_idx}[, {start}, {end}]) *regex:match_line()* Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end} are supplied, match only this byte index range. Otherwise see |regex:match_str()|. If {start} is used, then the returned byte @@ -728,18 +719,19 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* 1-based. Examples: > - vim.diff('a\n', 'b\nc\n') - --> - @@ -1 +1,2 @@ - -a - +b - +c - - vim.diff('a\n', 'b\nc\n', {result_type = 'indices'}) - --> - { - {1, 1, 1, 2} - } + + vim.diff('a\n', 'b\nc\n') + --> + @@ -1 +1,2 @@ + -a + +b + +c + + vim.diff('a\n', 'b\nc\n', {result_type = 'indices'}) + --> + { + {1, 1, 1, 2} + } < Parameters: ~ {a} First string to compare @@ -757,7 +749,7 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* • `result_type` (string): Form of the returned diff: • "unified": (default) String in unified format. • "indices": Array of hunk locations. - Note this option is ignored if `on_hunk` is + Note: This option is ignored if `on_hunk` is used. • `algorithm` (string): Diff algorithm to use. Values: @@ -792,31 +784,31 @@ VIM.MPACK *lua-mpack* The *vim.mpack* module provides encoding and decoding of Lua objects to and from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. -vim.mpack.encode({obj}) *vim.mpack.encode* +vim.mpack.encode({obj}) *vim.mpack.encode* Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. -vim.mpack.decode({str}) *vim.mpack.decode* +vim.mpack.decode({str}) *vim.mpack.decode* Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. ------------------------------------------------------------------------------ -VIM.SPELL *lua-spell* +VIM.SPELL *lua-spell* -vim.spell.check({str}) *vim.spell.check()* +vim.spell.check({str}) *vim.spell.check()* Check {str} for spelling errors. Similar to the Vimscript function |spellbadword()|. Note: The behaviour of this function is dependent on: 'spelllang', - 'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local - to the buffer. Consider calling this with |nvim_buf_call()|. + 'spellfile', 'spellcapcheck' and 'spelloptions' which can all be + local to the buffer. Consider calling this with |nvim_buf_call()|. Example: > + vim.spell.check("the quik brown fox") --> { {'quik', 'bad', 4} } < - Parameters: ~ {str} String to spell check. @@ -831,24 +823,24 @@ vim.spell.check({str}) *vim.spell.check()* - The position in {str} where the word begins. ------------------------------------------------------------------------------ -VIM *lua-builtin* +VIM *lua-builtin* -vim.api.{func}({...}) *vim.api* +vim.api.{func}({...}) *vim.api* Invokes Nvim |API| function {func} with arguments {...}. Example: call the "nvim_get_current_line()" API function: > print(tostring(vim.api.nvim_get_current_line())) -vim.version() *vim.version* +vim.version() *vim.version* Gets the version of the current Nvim build. -vim.in_fast_event() *vim.in_fast_event()* +vim.in_fast_event() *vim.in_fast_event()* Returns true if the code is executing as part of a "fast" event handler, where most of the API is disabled. These are low-level events (e.g. |lua-loop-callbacks|) which can be invoked whenever Nvim polls - for input. When this is `false` most API functions are callable (but + for input. When this is `false` most API functions are callable (but may be subject to other restrictions such as |textlock|). -vim.NIL *vim.NIL* +vim.NIL *vim.NIL* Special value representing NIL in |RPC| and |v:null| in Vimscript conversion, and similar cases. Lua `nil` cannot be used as part of a Lua table representing a Dictionary or Array, because it is @@ -860,10 +852,10 @@ vim.empty_dict() *vim.empty_dict()* Vimscript or API types. Nvim by default converts an empty table `{}` without this metatable to an list/array. - Note: if numeric keys are present in the table, Nvim ignores the + Note: If numeric keys are present in the table, Nvim ignores the metatable marker and converts the dict to a list/array anyway. -vim.rpcnotify({channel}, {method}[, {args}...]) *vim.rpcnotify()* +vim.rpcnotify({channel}, {method}[, {args}...]) *vim.rpcnotify()* Sends {event} to {channel} via |RPC| and returns immediately. If {channel} is 0, the event is broadcast to all channels. @@ -876,12 +868,12 @@ vim.rpcrequest({channel}, {method}[, {args}...]) *vim.rpcrequest()* Note: NIL values as part of the return value is represented as |vim.NIL| special value -vim.stricmp({a}, {b}) *vim.stricmp()* - Compares strings case-insensitively. Returns 0, 1 or -1 if strings +vim.stricmp({a}, {b}) *vim.stricmp()* + Compares strings case-insensitively. Returns 0, 1 or -1 if strings are equal, {a} is greater than {b} or {a} is lesser than {b}, respectively. -vim.str_utfindex({str}[, {index}]) *vim.str_utfindex()* +vim.str_utfindex({str}[, {index}]) *vim.str_utfindex()* 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. @@ -891,21 +883,21 @@ vim.str_utfindex({str}[, {index}]) *vim.str_utfindex()* point each. An {index} in the middle of a UTF-8 sequence is rounded upwards to the end of that sequence. -vim.str_byteindex({str}, {index}[, {use_utf16}]) *vim.str_byteindex()* +vim.str_byteindex({str}, {index}[, {use_utf16}]) *vim.str_byteindex()* Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not supplied, it defaults to false (use UTF-32). Returns the byte index. - Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|. An {index} - in the middle of a UTF-16 sequence is rounded upwards to the end of that - sequence. + Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|. + An {index} in the middle of a UTF-16 sequence is rounded upwards to + the end of that sequence. -vim.schedule({callback}) *vim.schedule()* +vim.schedule({callback}) *vim.schedule()* Schedules {callback} to be invoked soon by the main event-loop. Useful to avoid |textlock| or other temporary restrictions. -vim.defer_fn({fn}, {timeout}) *vim.defer_fn* - Defers calling {fn} until {timeout} ms passes. Use to do a one-shot timer +vim.defer_fn({fn}, {timeout}) *vim.defer_fn* + Defers calling {fn} until {timeout} ms passes. Use to do a one-shot timer that calls {fn}. Note: The {fn} is |schedule_wrap|ped automatically, so API functions are @@ -969,15 +961,15 @@ vim.wait({time} [, {callback}, {interval}, {fast_only}]) *vim.wait()* end < -vim.type_idx *vim.type_idx* - Type index for use in |lua-special-tbl|. Specifying one of the values +vim.type_idx *vim.type_idx* + Type index for use in |lua-special-tbl|. Specifying one of the values from |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 + integral numbers to be |Float|. See |lua-special-tbl| for more details. -vim.val_idx *vim.val_idx* - Value index for tables representing |Float|s. A table representing +vim.val_idx *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, @@ -985,17 +977,17 @@ vim.val_idx *vim.val_idx* } < See also |vim.type_idx| and |lua-special-tbl|. -vim.types *vim.types* - Table with possible values for |vim.type_idx|. Contains two sets of +vim.types *vim.types* + Table with possible values for |vim.type_idx|. Contains two sets of key-value pairs: first maps possible values for |vim.type_idx| to human-readable strings, second maps human-readable type names to - values for |vim.type_idx|. Currently contains pairs for `float`, + values for |vim.type_idx|. Currently contains pairs for `float`, `array` and `dictionary` types. - Note: one must expect that values corresponding to `vim.types.float`, + 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 + 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`. @@ -1015,33 +1007,22 @@ Log levels are one of the values defined in `vim.log.levels`: vim.log.levels.OFF ------------------------------------------------------------------------------ -LUA-VIMSCRIPT BRIDGE *lua-vimscript* +LUA-VIMSCRIPT BRIDGE *lua-vimscript* Nvim Lua provides an interface to Vimscript variables and functions, and editor commands and options. See also https://github.com/nanotee/nvim-lua-guide. -vim.call({func}, {...}) *vim.call()* +vim.call({func}, {...}) *vim.call()* Invokes |vim-function| or |user-function| {func} with arguments {...}. See also |vim.fn|. Equivalent to: > vim.fn[func]({...}) -vim.cmd({cmd}) *vim.cmd()* - Executes multiple lines of Vimscript at once. It is an alias to - |nvim_exec()|, where `output` is set to false. Thus it works identical - to |:source|. - See also |ex-cmd-index|. - Example: > - vim.cmd('echo 42') - vim.cmd([[ - augroup My_group - autocmd! - autocmd FileType c setlocal cindent - augroup END - ]]) - -vim.fn.{func}({...}) *vim.fn* +vim.cmd({command}) + See |vim.cmd()|. + +vim.fn.{func}({...}) *vim.fn* Invokes |vim-function| or |user-function| {func} with arguments {...}. To call autoload functions, use the syntax: > vim.fn['some#function']({...}) @@ -1058,7 +1039,7 @@ vim.fn.{func}({...}) *vim.fn* enumerates functions that were called at least once. - *lua-vim-variables* + *lua-vim-variables* The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables described below. In this way you can easily read and modify global Vimscript @@ -1070,31 +1051,31 @@ Example: > print(vim.g.foo) -- Get and print the g:foo Vimscript variable. vim.g.foo = nil -- Delete (:unlet) the Vimscript variable. vim.b[2].foo = 6 -- Set b:foo for buffer 2 - -vim.g *vim.g* +< +vim.g *vim.g* Global (|g:|) editor variables. Key with no value returns `nil`. -vim.b *vim.b* +vim.b *vim.b* Buffer-scoped (|b:|) variables for the current buffer. Invalid or unset key returns `nil`. Can be indexed with an integer to access variables for a specific buffer. -vim.w *vim.w* +vim.w *vim.w* Window-scoped (|w:|) variables for the current window. Invalid or unset key returns `nil`. Can be indexed with an integer to access variables for a specific window. -vim.t *vim.t* +vim.t *vim.t* Tabpage-scoped (|t:|) variables for the current tabpage. Invalid or unset key returns `nil`. Can be indexed with an integer to access variables for a specific tabpage. -vim.v *vim.v* +vim.v *vim.v* |v:| variables. Invalid or unset key returns `nil`. -vim.env *vim.env* +vim.env *vim.env* Environment variables defined in the editor session. See |expand-env| and |:let-environment| for the Vimscript behavior. Invalid or unset key returns `nil`. @@ -1144,7 +1125,6 @@ from within Lua. -- or using the `:append(...)` method vim.opt.wildignore:append { "*.pyc", "node_modules" } < - To replicate the behavior of |:set^=|, use: > -- vim.opt supports prepending options via the "^" operator @@ -1265,14 +1245,13 @@ vim.o :set set set vim.bo/vim.wo :setlocal - set vim.go :setglobal set - -vim.o *vim.o* +vim.o *vim.o* Get or set editor options, like |:set|. Invalid key is an error. Example: > vim.o.cmdheight = 4 print(vim.o.columns) - - -vim.go *vim.go* +< +vim.go *vim.go* Get or set an |option|. Invalid key is an error. This is a wrapper around |nvim_set_option()| and |nvim_get_option()|. @@ -1284,8 +1263,7 @@ vim.go *vim.go* Example: > vim.go.cmdheight = 4 < - -vim.bo *vim.bo* +vim.bo *vim.bo* Get or set buffer-scoped |local-options|. Invalid key is an error. This is a wrapper around |nvim_buf_set_option()| and @@ -1294,8 +1272,8 @@ vim.bo *vim.bo* Example: > vim.bo.buflisted = true print(vim.bo.comments) - -vim.wo *vim.wo* +< +vim.wo *vim.wo* Get or set window-scoped |local-options|. Invalid key is an error. This is a wrapper around |nvim_win_set_option()| and @@ -1304,11 +1282,38 @@ vim.wo *vim.wo* Example: > vim.wo.cursorcolumn = true print(vim.wo.foldmarker) - - +< ============================================================================== Lua module: vim *lua-vim* +cmd({command}) *vim.cmd()* + Execute Vim script commands. + + Example: > + + vim.cmd('echo 42') + vim.cmd([[ + augroup My_group + autocmd! + autocmd FileType c setlocal cindent + augroup END + ]]) + vim.cmd({ cmd = 'echo', args = { '"foo"' } }) +< + + Parameters: ~ + {command} string|table Command(s) to execute. If a + string, executes multiple lines of Vim script + at once. In this case, it is an alias to + |nvim_exec()|, where `output` is set to false. + Thus it works identical to |:source|. If a + table, executes a single command. In this case, + it is an alias to |nvim_cmd()| where `opts` is + empty. + + See also: ~ + |ex-cmd-index| + *vim.connection_failure_errmsg()* connection_failure_errmsg({consequence}) TODO: Documentation @@ -1327,16 +1332,20 @@ defer_fn({fn}, {timeout}) *vim.defer_fn()* Return: ~ timer luv timer object -deprecate({name}, {alternative}, {version}, {plugin}) *vim.deprecate()* + *vim.deprecate()* +deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) Display a deprecation notification to the user. Parameters: ~ {name} string Deprecated function. - {alternative} string|nil Preferred alternative function. + {alternative} (string|nil) Preferred alternative + function. {version} string Version in which the deprecated function will be removed. {plugin} string|nil Plugin name that the function will be removed from. Defaults to "Nvim". + {backtrace} boolean|nil Prints backtrace. Defaults to + true. inspect({object}, {options}) *vim.inspect()* Return a human-readable representation of the given object. @@ -1353,11 +1362,12 @@ notify({msg}, {level}, {opts}) *vim.notify()* notification provider). By default, writes to |:messages|. Parameters: ~ - {msg} string Content of the notification to show to the - user. - {level} number|nil One of the values from + {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. + {opts} (table|nil) Optional parameters. Unused by + default. notify_once({msg}, {level}, {opts}) *vim.notify_once()* Display a notification only one time. @@ -1366,11 +1376,15 @@ notify_once({msg}, {level}, {opts}) *vim.notify_once()* 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 + {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. + {opts} (table|nil) Optional parameters. Unused by + default. + + Return: ~ + (boolean) true if message was displayed, else false on_key({fn}, {ns_id}) *vim.on_key()* Adds Lua function {fn} with namespace id {ns_id} as a listener @@ -1396,8 +1410,8 @@ on_key({fn}, {ns_id}) *vim.on_key()* returns a new |nvim_create_namespace()| id. Return: ~ - number Namespace id associated with {fn}. Or count of all - callbacks if on_key() is called without arguments. + (number) Namespace id associated with {fn}. Or count of + all callbacks if on_key() is called without arguments. Note: {fn} will be removed if an error occurs while calling. @@ -1451,12 +1465,12 @@ region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* marked by two points Parameters: ~ - {bufnr} number of buffer + {bufnr} (number) of buffer {pos1} (line, column) tuple marking beginning of region {pos2} (line, column) tuple marking end of region {regtype} type of selection (:help setreg) - {inclusive} boolean indicating whether the selection is + {inclusive} (boolean) indicating whether the selection is end-inclusive Return: ~ @@ -1476,14 +1490,14 @@ schedule_wrap({cb}) *vim.schedule_wrap()* deep_equal({a}, {b}) *vim.deep_equal()* Deep compare values for equality - Tables are compared recursively unless they both provide the `eq` methamethod. All other types are compared using the equality `==` operator. + Tables are compared recursively unless they both provide the `eq` metamethod. All other types are compared using the equality `==` operator. Parameters: ~ - {a} first value - {b} second value + {a} any First value + {b} any Second value Return: ~ - `true` if values are equals, else `false`. + (boolean) `true` if values are equals, else `false` deepcopy({orig}) *vim.deepcopy()* Returns a deep copy of the given object. Non-table objects are @@ -1494,32 +1508,32 @@ deepcopy({orig}) *vim.deepcopy()* and will throw an error. Parameters: ~ - {orig} table Table to copy + {orig} (table) Table to copy Return: ~ - New table of copied keys and (nested) values. + (table) Table of copied keys and (nested) values. endswith({s}, {suffix}) *vim.endswith()* Tests if `s` ends with `suffix`. Parameters: ~ - {s} (string) a string - {suffix} (string) a suffix + {s} (string) String + {suffix} (string) Suffix to match Return: ~ - (boolean) true if `suffix` is a suffix of s + (boolean) `true` if `suffix` is a suffix of `s` gsplit({s}, {sep}, {plain}) *vim.gsplit()* Splits a string at each instance of a separator. Parameters: ~ - {s} String to split - {sep} Separator string or pattern - {plain} If `true` use `sep` literally (passed to - String.find) + {s} (string) String to split + {sep} (string) Separator or pattern + {plain} (boolean) If `true` use `sep` literally (passed + to string.find) Return: ~ - Iterator over the split components + (function) Iterator over the split components See also: ~ |vim.split()| @@ -1530,10 +1544,10 @@ is_callable({f}) *vim.is_callable()* Returns true if object `f` can be called as a function. Parameters: ~ - {f} Any object + {f} any Any object Return: ~ - true if `f` is callable, else false + (boolean) `true` if `f` is callable, else `false` list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* Extends a list-like table with the values of another list-like @@ -1542,13 +1556,14 @@ list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* NOTE: This mutates dst! Parameters: ~ - {dst} list which will be modified and appended to. - {src} list from which values will be inserted. - {start} Start index on src. defaults to 1 - {finish} Final index on src. defaults to #src + {dst} (table) List which will be modified and appended + to + {src} (table) List from which values will be inserted + {start} (number) Start index on src. Defaults to 1 + {finish} (number) Final index on src. Defaults to `#src` Return: ~ - dst + (table) dst See also: ~ |vim.tbl_extend()| @@ -1558,21 +1573,22 @@ list_slice({list}, {start}, {finish}) *vim.list_slice()* to end (inclusive) Parameters: ~ - {list} table table - {start} integer Start range of slice - {finish} integer End range of slice + {list} (table) Table + {start} (number) Start range of slice + {finish} (number) End range of slice Return: ~ - Copy of table sliced from start to finish (inclusive) + (table) Copy of table sliced from start to finish + (inclusive) pesc({s}) *vim.pesc()* Escapes magic chars in a Lua pattern. Parameters: ~ - {s} String to escape + {s} (string) String to escape Return: ~ - %-escaped pattern string + (string) %-escaped pattern string See also: ~ https://github.com/rxi/lume @@ -1589,16 +1605,16 @@ split({s}, {sep}, {kwargs}) *vim.split()* < Parameters: ~ - {s} String to split - {sep} Separator string or pattern - {kwargs} Keyword arguments: + {s} (string) String to split + {sep} (string) Separator or pattern + {kwargs} (table) Keyword arguments: • plain: (boolean) If `true` use `sep` literally (passed to string.find) • trimempty: (boolean) If `true` remove empty items from the front and back of the list Return: ~ - List-like table of the split components. + (table) List of split components See also: ~ |vim.gsplit()| @@ -1607,28 +1623,34 @@ startswith({s}, {prefix}) *vim.startswith()* Tests if `s` starts with `prefix`. Parameters: ~ - {s} (string) a string - {prefix} (string) a prefix + {s} (string) String + {prefix} (string) Prefix to match Return: ~ - (boolean) true if `prefix` is a prefix of s + (boolean) `true` if `prefix` is a prefix of `s` tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* Add the reverse lookup values to an existing table. For - example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }` + example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = + 1 }` + + Note that this modifies the input. Parameters: ~ - {o} table The table to add the reverse to. + {o} (table) Table to add the reverse to + + Return: ~ + (table) o tbl_contains({t}, {value}) *vim.tbl_contains()* Checks if a list-like (vector) table contains `value`. Parameters: ~ - {t} Table to check - {value} Value to compare + {t} (table) Table to check + {value} any Value to compare Return: ~ - true if `t` contains `value` + (boolean) `true` if `t` contains `value` tbl_count({t}) *vim.tbl_count()* Counts the number of non-nil values in table `t`. @@ -1639,10 +1661,10 @@ tbl_count({t}) *vim.tbl_count()* < Parameters: ~ - {t} Table + {t} (table) Table Return: ~ - Number that is the number of the value in table + (number) Number of non-nil values in table See also: ~ https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua @@ -1651,12 +1673,15 @@ tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* Merges recursively two or more map-like tables. Parameters: ~ - {behavior} Decides what to do if a key is found in more - than one map: + {behavior} (string) Decides what to do if a key is found + in more than one map: • "error": raise an error • "keep": use value from the leftmost map • "force": use value from the rightmost map - {...} Two or more map-like tables. + {...} (table) Two or more map-like tables + + Return: ~ + (table) Merged table See also: ~ |tbl_extend()| @@ -1665,12 +1690,15 @@ tbl_extend({behavior}, {...}) *vim.tbl_extend()* Merges two or more map-like tables. Parameters: ~ - {behavior} Decides what to do if a key is found in more - than one map: + {behavior} (string) Decides what to do if a key is found + in more than one map: • "error": raise an error • "keep": use value from the leftmost map • "force": use value from the rightmost map - {...} Two or more map-like tables. + {...} (table) Two or more map-like tables + + Return: ~ + (table) Merged table See also: ~ |extend()| @@ -1679,43 +1707,51 @@ tbl_filter({func}, {t}) *vim.tbl_filter()* Filter a table using a predicate function Parameters: ~ - {func} function or callable table - {t} table + {func} function|table Function or callable table + {t} (table) Table + + Return: ~ + (table) Table of filtered values tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are "unrolled" and appended to the result. Parameters: ~ - {t} List-like table + {t} (table) List-like table Return: ~ - Flattened copy of the given list-like table. + (table) Flattened copy of the given list-like table See also: ~ From https://github.com/premake/premake-core/blob/master/src/base/table.lua tbl_get({o}, {...}) *vim.tbl_get()* Index into a table (first argument) via string keys passed as - subsequent arguments. Return `nil` if the key does not exist. Examples: > + subsequent arguments. Return `nil` if the key does not exist. + + Examples: > vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil < Parameters: ~ - {o} Table to index - {...} Optional strings (0 or more, variadic) via which to - index the table + {o} (table) Table to index + {...} (string) Optional strings (0 or more, variadic) via + which to index the table Return: ~ - nested value indexed by key if it exists, else nil + any Nested value indexed by key (if it exists), else nil tbl_isempty({t}) *vim.tbl_isempty()* Checks if a table is empty. Parameters: ~ - {t} Table to check + {t} (table) Table to check + + Return: ~ + (boolean) `true` if `t` is empty See also: ~ https://github.com/premake/premake-core/blob/master/src/base/table.lua @@ -1729,20 +1765,20 @@ tbl_islist({t}) *vim.tbl_islist()* |vim.fn|. Parameters: ~ - {t} Table + {t} (table) Table Return: ~ - `true` if array-like table, else `false`. + (boolean) `true` if array-like table, else `false` tbl_keys({t}) *vim.tbl_keys()* Return a list of all keys used in a table. However, the order of the return table of keys is not guaranteed. Parameters: ~ - {t} Table + {t} (table) Table Return: ~ - list of keys + (table) List of keys See also: ~ From https://github.com/premake/premake-core/blob/master/src/base/table.lua @@ -1751,28 +1787,32 @@ tbl_map({func}, {t}) *vim.tbl_map()* Apply a function to all values of a table. Parameters: ~ - {func} function or callable table - {t} table + {func} function|table Function or callable table + {t} (table) Table + + Return: ~ + (table) Table of transformed values tbl_values({t}) *vim.tbl_values()* Return a list of all values used in a table. However, the order of the return table of values is not guaranteed. Parameters: ~ - {t} Table + {t} (table) Table Return: ~ - list of values + (table) List of values trim({s}) *vim.trim()* Trim whitespace (Lua pattern "%s") from both sides of a string. Parameters: ~ - {s} String to trim + {s} (string) String to trim Return: ~ - String with whitespace removed from its beginning and end + (string) String with whitespace removed from its beginning + and end See also: ~ https://www.lua.org/pil/20.2.html @@ -1814,7 +1854,7 @@ validate({opt}) *vim.validate()* < Parameters: ~ - {opt} table of parameter names to validations. Each key + {opt} (table) Names of parameters to validate. Each key is a parameter name; each value is a tuple in one of these forms: 1. (arg_value, type_name, optional) @@ -1844,38 +1884,38 @@ uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* Get a URI from a bufnr Parameters: ~ - {bufnr} number + {bufnr} (number) Return: ~ - string URI + (string) URI uri_from_fname({path}) *vim.uri_from_fname()* Get a URI from a file path. Parameters: ~ - {path} string Path to file + {path} (string) Path to file Return: ~ - string URI + (string) URI uri_to_bufnr({uri}) *vim.uri_to_bufnr()* Get the buffer for a uri. Creates a new unloaded buffer if no buffer for the uri already exists. Parameters: ~ - {uri} string + {uri} (string) Return: ~ - number bufnr + (number) bufnr uri_to_fname({uri}) *vim.uri_to_fname()* Get a filename from a URI Parameters: ~ - {uri} string + {uri} (string) Return: ~ - string filename or unchanged URI for non-file URIs + (string) filename or unchanged URI for non-file URIs ============================================================================== @@ -1892,7 +1932,7 @@ input({opts}, {on_confirm}) *vim.ui.input()* < Parameters: ~ - {opts} table Additional options. See |input()| + {opts} (table) Additional options. See |input()| • prompt (string|nil) Text of the prompt. Defaults to `Input:`. • default (string|nil) Default reply to the @@ -1905,10 +1945,10 @@ input({opts}, {on_confirm}) *vim.ui.input()* |:command-completion| • highlight (function) Function that will be used for highlighting user inputs. - {on_confirm} function ((input|nil) -> ()) Called once the - user confirms or abort the input. `input` is - what the user typed. `nil` if the user - aborted the dialog. + {on_confirm} (function) ((input|nil) -> ()) Called once + the user confirms or abort the input. + `input` is what the user typed. `nil` if the + user aborted the dialog. select({items}, {opts}, {on_choice}) *vim.ui.select()* Prompts the user to pick a single item from a collection of @@ -1931,8 +1971,8 @@ select({items}, {opts}, {on_choice}) *vim.ui.select()* < Parameters: ~ - {items} table Arbitrary items - {opts} table Additional options + {items} (table) Arbitrary items + {opts} (table) Additional options • prompt (string|nil) Text of the prompt. Defaults to `Select one of:` • format_item (function item -> text) @@ -1944,7 +1984,7 @@ select({items}, {opts}, {on_choice}) *vim.ui.select()* use this to infer the structure or semantics of `items`, or the context in which select() was called. - {on_choice} function ((item|nil, idx|nil) -> ()) Called + {on_choice} (function) ((item|nil, idx|nil) -> ()) Called once the user made a choice. `idx` is the 1-based index of `item` within `items`. `nil` if the user aborted the dialog. @@ -2013,16 +2053,16 @@ add({filetypes}) *vim.filetype.add()* < Parameters: ~ - {filetypes} table A table containing new filetype maps + {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. + {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. @@ -2038,7 +2078,7 @@ del({modes}, {lhs}, {opts}) *vim.keymap.del()* < Parameters: ~ - {opts} table A table of optional arguments: + {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. @@ -2082,12 +2122,12 @@ set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* {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. + {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. If a Lua function and `opts.expr == true`, returning `nil` is equivalent to an empty string. - {opts} table A table of |:map-arguments| such as + {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: diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 6e100e5854..98da68b76a 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -105,7 +105,7 @@ modes. command applies. Use the <buffer> argument to remove buffer-local mappings |:map-<buffer>| - Warning: This also removes the default mappings. + Warning: This also removes the |default-mappings|. :map |mapmode-nvo| :nm[ap] |mapmode-n| @@ -796,9 +796,8 @@ command. For example: > :noremap j k This will exchange the cursor up and down commands. -With the normal :map command, when the 'remap' option is on, mapping takes -place until the text is found not to be a part of a {lhs}. For example, if -you use: > +With the normal :map command mapping takes place until the text is found not +to be a part of a {lhs}. For example, if you use: > :map x y :map y x Vim will replace x with y, and then y with x, etc. When this has happened diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 1109056d47..b49512e1e6 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -841,7 +841,7 @@ A jump table for the options with a short description can be found at |Q_op|. again not rename the file. *'backupdir'* *'bdir'* -'backupdir' 'bdir' string (default ".,$XDG_DATA_HOME/nvim/backup//") +'backupdir' 'bdir' string (default ".,$XDG_STATE_HOME/nvim/backup//") global List of directories for the backup file, separated with commas. - The backup file will be created in the first directory in the list @@ -2063,7 +2063,7 @@ A jump table for the options with a short description can be found at |Q_op|. {char2}. See |digraphs|. *'directory'* *'dir'* -'directory' 'dir' string (default "$XDG_DATA_HOME/nvim/swap//") +'directory' 'dir' string (default "$XDG_STATE_HOME/nvim/swap//") global List of directory names for the swap file, separated with commas. @@ -2452,6 +2452,7 @@ A jump table for the options with a short description can be found at |Q_op|. item default Used for ~ stl:c ' ' or '^' statusline of the current window stlnc:c ' ' or '=' statusline of the non-current windows + wbr:c ' ' window bar horiz:c '─' or '-' horizontal separators |:split| horizup:c '┴' or '-' upwards facing horizontal separator horizdown:c '┬' or '-' downwards facing horizontal separator @@ -2492,6 +2493,7 @@ A jump table for the options with a short description can be found at |Q_op|. item highlight group ~ stl:c StatusLine |hl-StatusLine| stlnc:c StatusLineNC |hl-StatusLineNC| + wbr:c WinBar |hl-WinBar| or |hl-WinBarNC| horiz:c WinSeparator |hl-WinSeparator| horizup:c WinSeparator |hl-WinSeparator| horizdown:c WinSeparator |hl-WinSeparator| @@ -3502,7 +3504,7 @@ A jump table for the options with a short description can be found at |Q_op|. option. For '@' only characters up to 255 are used. Careful: If you change this option, it might break expanding environment variables. E.g., when '/' is included and Vim tries to - expand "$HOME/.local/share/nvim/shada/main.shada". Maybe you should + expand "$HOME/.local/state/nvim/shada/main.shada". Maybe you should change 'iskeyword' instead. *'iskeyword'* *'isk'* @@ -4798,15 +4800,6 @@ A jump table for the options with a short description can be found at |Q_op|. 'number', see |number_relativenumber| for all combinations of the two options. - *'remap'* *'noremap'* -'remap' boolean (default on) - global - Allows for mappings to work recursively. If you do not want this for - a single entry, use the :noremap[!] command. - NOTE: To avoid portability problems with Vim scripts, always keep - this option at the default "on". Only switch it off when working with - old Vi scripts. - *'report'* 'report' number (default 2) global @@ -4942,9 +4935,12 @@ A jump table for the options with a short description can be found at |Q_op|. but are not part of the Nvim distribution. XDG_DATA_DIRS defaults to /usr/local/share/:/usr/share/, so system administrators are expected to install site plugins to /usr/share/nvim/site. - 5. $VIMRUNTIME, for files distributed with Neovim. + 5. Applications state home directory, for files that contain your + session state (eg. backupdir, viewdir, undodir, etc). + Given by `stdpath("state")`. |$XDG_STATE_HOME| + 6. $VIMRUNTIME, for files distributed with Neovim. *after-directory* - 6, 7, 8, 9. In after/ subdirectories of 1, 2, 3 and 4, with reverse + 7, 8, 9, 10. In after/ subdirectories of 1, 2, 3 and 4, with reverse ordering. This is for preferences to overrule or add to the distributed defaults or system-wide settings (rarely needed). @@ -6475,13 +6471,6 @@ A jump table for the options with a short description can be found at |Q_op|. C1 Control characters 0x80...0x9F - *'terse'* *'noterse'* -'terse' boolean (default off) - global - When set: Add 's' flag to 'shortmess' option (this makes the message - for a search that hits the start or end of the file not being - displayed). When reset: Remove 's' flag from 'shortmess' option. - *'textwidth'* *'tw'* 'textwidth' 'tw' number (default 0) local to buffer @@ -6623,7 +6612,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'ttyfast' 'tf' Removed. |vim-differences| *'undodir'* *'udir'* *E5003* -'undodir' 'udir' string (default "$XDG_DATA_HOME/nvim/undo//") +'undodir' 'udir' string (default "$XDG_STATE_HOME/nvim/undo//") global List of directory names for undo files, separated with commas. See 'backupdir' for details of the format. @@ -6786,7 +6775,7 @@ A jump table for the options with a short description can be found at |Q_op|. displayed when 'verbosefile' is set. *'viewdir'* *'vdir'* -'viewdir' 'vdir' string (default: "$XDG_DATA_HOME/nvim/view//") +'viewdir' 'vdir' string (default: "$XDG_STATE_HOME/nvim/view//") global Name of the directory where to store files for |:mkview|. This option cannot be set from a |modeline| or in the |sandbox|, for @@ -7042,6 +7031,19 @@ A jump table for the options with a short description can be found at |Q_op|. key is never used for the menu. This option is not used for <F10>; on Win32. + *'winbar'* *'wbr'* +'winbar' 'wbr' string (default empty) + global or local to window |global-local| + When non-empty, this option enables the window bar and determines its + contents. The window bar is a bar that's shown at the top of every + window with it enabled. The value of 'winbar' is evaluated like with + 'statusline'. + + When changing something that is used in 'winbar' that does not trigger + it to be updated, use |:redrawstatus|. + + This option cannot be set in a modeline when 'modelineexpr' is off. + *'winblend'* *'winbl'* 'winblend' 'winbl' number (default 0) local to window diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index 35f5b311ff..371a210847 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -71,12 +71,18 @@ N Repeat the latest "/" or "?" [count] times in Only whole keywords are searched for, like with the command "/\<keyword\>". |exclusive| 'ignorecase' is used, 'smartcase' is not. + *v_star-default* + In Visual mode, search forward for the current selection. + |default-mappings| *#* # Same as "*", but search backward. The pound sign (character 163) also works. If the "#" key works as backspace, try using "stty erase <BS>" before starting Vim (<BS> is CTRL-H or a real backspace). + *v_#-default* + In Visual mode, search backward for the current selection. + |default-mappings| *gstar* g* Like "*", but don't put "\<" and "\>" around the word. diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 961d734bfe..ff7e2ab400 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -824,7 +824,6 @@ Short explanation of each option: *option-list* 'redrawtime' 'rdt' timeout for 'hlsearch' and |:match| highlighting 'regexpengine' 're' default regexp engine to use 'relativenumber' 'rnu' show relative line number in front of each line -'remap' allow mappings to work recursively 'report' threshold for reporting nr. of lines changed 'revins' 'ri' inserting characters will work backwards 'rightleft' 'rl' window is right-to-left oriented @@ -896,7 +895,6 @@ Short explanation of each option: *option-list* 'tagstack' 'tgst' push tags onto the tag stack 'term' name of the terminal 'termbidi' 'tbidi' terminal takes care of bi-directionality -'terse' shorten some messages 'textwidth' 'tw' maximum width of text that is being inserted 'thesaurus' 'tsr' list of thesaurus files for keyword completion 'thesaurusfunc' 'tsrfu' function to be used for thesaurus completion diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 1d3fa6c2ca..f542f33451 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -367,7 +367,7 @@ argument. *--headless* --headless Start without UI, and do not wait for `nvim_ui_attach`. The builtin TUI is not used, so stdio works as an arbitrary - communication channel. |channel-stdio| + communication channel. |channel-stdio| Also useful for scripting (tests) to see messages that would not be printed by |-es|. @@ -584,7 +584,7 @@ setting can affect the entire editor in ways that are not initially obvious. To find the cause of a problem in your config, you must "bisect" it: 1. Remove or disable half of your |config|. 2. Restart Nvim. -3. If the problem still occurs, goto 1. +3. If the problem still occurs, goto 1. 4. If the problem is gone, restore half of the removed lines. 5. Continue narrowing your config in this way, until you find the setting or plugin causing the issue. @@ -701,7 +701,7 @@ vimrc file. These commands will write ":map" and ":set" commands to a file, in such a way that when these commands are executed, the current key mappings and options will be set to the same values. The options 'columns', 'endofline', -'fileformat', 'lines', 'modified', and 'scroll' are not included, because +'fileformat', 'lines', 'modified', and 'scroll' are not included, because these are terminal or file dependent. Note that the options 'binary', 'paste' and 'readonly' are included, this might not always be what you want. @@ -718,7 +718,7 @@ with ":map" and ":set" commands and write the modified file. First read the default vimrc in with a command like ":source ~piet/.vimrc.Cprogs", change the settings and then save them in the current directory with ":mkvimrc!". If you want to make this file your default |config|, move it to -$XDG_CONFIG_HOME/nvim. You could also use autocommands |autocommand| and/or +$XDG_CONFIG_HOME/nvim. You could also use autocommands |autocommand| and/or modelines |modeline|. *vimrc-option-example* @@ -886,7 +886,7 @@ Shada ("shared data") file *shada* *shada-file* If you exit Vim and later start it again, you would normally lose a lot of information. The ShaDa file can be used to remember that information, which -enables you to continue where you left off. Its name is the abbreviation of +enables you to continue where you left off. Its name is the abbreviation of SHAred DAta because it is used for sharing data between Neovim sessions. This is introduced in section |21.3| of the user manual. @@ -917,9 +917,9 @@ The |v:oldfiles| variable is filled. The marks are not read in at startup option upon startup. *shada-write* -When Vim exits and 'shada' is non-empty, the info is stored in the ShaDa file -(it's actually merged with the existing one, if one exists |shada-merging|). -The 'shada' option is a string containing information about what info should +When Vim exits and 'shada' is non-empty, the info is stored in the ShaDa file +(it's actually merged with the existing one, if one exists |shada-merging|). +The 'shada' option is a string containing information about what info should be stored, and contains limits on how much should be stored (see 'shada'). Notes for Unix: @@ -977,75 +977,75 @@ remembered. MERGING *shada-merging* -When writing ShaDa files with |:wshada| without bang or at regular exit -information in the existing ShaDa file is merged with information from current -Neovim instance. For this purpose ShaDa files store timestamps associated +When writing ShaDa files with |:wshada| without bang or at regular exit +information in the existing ShaDa file is merged with information from current +Neovim instance. For this purpose ShaDa files store timestamps associated with ShaDa entries. Specifically the following is being done: -1. History lines are merged, ordered by timestamp. Maximum amount of items in - ShaDa file is defined by 'shada' option (|shada-/|, |shada-:|, |shada-@|, - etc: one suboption for each character that represents history name +1. History lines are merged, ordered by timestamp. Maximum amount of items in + ShaDa file is defined by 'shada' option (|shada-/|, |shada-:|, |shada-@|, + etc: one suboption for each character that represents history name (|:history|)). -2. Local marks and changes for files that were not opened by Neovim are copied - to new ShaDa file. Marks for files that were opened by Neovim are merged, +2. Local marks and changes for files that were not opened by Neovim are copied + to new ShaDa file. Marks for files that were opened by Neovim are merged, changes to files opened by Neovim are ignored. |shada-'| -3. Jump list is merged: jumps are ordered by timestamp, identical jumps +3. Jump list is merged: jumps are ordered by timestamp, identical jumps (identical position AND timestamp) are squashed. -4. Search patterns and substitute strings are not merged: search pattern or - substitute string which has greatest timestamp will be the only one copied +4. Search patterns and substitute strings are not merged: search pattern or + substitute string which has greatest timestamp will be the only one copied to ShaDa file. -5. For each register entity with greatest timestamp is the only saved. +5. For each register entity with greatest timestamp is the only saved. |shada-<| -6. All saved variables are saved from current Neovim instance. Additionally - existing variable values are copied, meaning that the only way to remove - variable from a ShaDa file is either removing it by hand or disabling +6. All saved variables are saved from current Neovim instance. Additionally + existing variable values are copied, meaning that the only way to remove + variable from a ShaDa file is either removing it by hand or disabling writing variables completely. |shada-!| 7. For each global mark entity with greatest timestamp is the only saved. -8. Buffer list and header are the only entries which are not merged in any - fashion: the only header and buffer list present are the ones from the +8. Buffer list and header are the only entries which are not merged in any + fashion: the only header and buffer list present are the ones from the Neovim instance which was last writing the file. |shada-%| COMPATIBILITY *shada-compatibility* ShaDa files are forward and backward compatible. This means that -1. Entries which have unknown type (i.e. that hold unidentified data) are +1. Entries which have unknown type (i.e. that hold unidentified data) are ignored when reading and blindly copied when writing. -2. Register entries with unknown register name are ignored when reading and - blindly copied when writing. Limitation: only registers that use name with +2. Register entries with unknown register name are ignored when reading and + blindly copied when writing. Limitation: only registers that use name with code in interval [1, 255] are supported. |registers| -3. Register entries with unknown register type are ignored when reading and +3. Register entries with unknown register type are ignored when reading and merged as usual when writing. |getregtype()| -4. Local and global mark entries with unknown mark names are ignored when - reading. When writing global mark entries are blindly copied and local mark - entries are also blindly copied, but only if file they are attached to fits - in the |shada-'| limit. Unknown local mark entry's timestamp is also taken - into account when calculating which files exactly should fit into this - limit. Limitation: only marks that use name with code in interval [1, 255] +4. Local and global mark entries with unknown mark names are ignored when + reading. When writing global mark entries are blindly copied and local mark + entries are also blindly copied, but only if file they are attached to fits + in the |shada-'| limit. Unknown local mark entry's timestamp is also taken + into account when calculating which files exactly should fit into this + limit. Limitation: only marks that use name with code in interval [1, 255] are supported. |mark-motions| -5. History entries with unknown history type are ignored when reading and - blindly copied when writing. Limitation: there can be only up to 256 +5. History entries with unknown history type are ignored when reading and + blindly copied when writing. Limitation: there can be only up to 256 history types. |history| -6. Unknown keys found in register, local mark, global mark, change, jump and - search pattern entries are saved internally and dumped when writing. +6. Unknown keys found in register, local mark, global mark, change, jump and + search pattern entries are saved internally and dumped when writing. Entries created during Neovim session never have such additions. -7. Additional elements found in replacement string and history entries are - saved internally and dumped. Entries created during Neovim session never +7. Additional elements found in replacement string and history entries are + saved internally and dumped. Entries created during Neovim session never have such additions. -8. Additional elements found in variable entries are simply ignored when - reading. When writing new variables they will be preserved during merging, - but that's all. Variable values dumped from current Neovim session never - have additional elements, even if variables themselves were obtained by +8. Additional elements found in variable entries are simply ignored when + reading. When writing new variables they will be preserved during merging, + but that's all. Variable values dumped from current Neovim session never + have additional elements, even if variables themselves were obtained by reading ShaDa files. -"Blindly" here means that there will be no attempts to somehow merge them, +"Blindly" here means that there will be no attempts to somehow merge them, even if other entries (with known name/type/etc) are merged. |shada-merging| SHADA FILE NAME *shada-file-name* - Default name of the |shada| file is: - Unix: "$XDG_DATA_HOME/nvim/shada/main.shada" - Windows: "$XDG_DATA_HOME/nvim-data/shada/main.shada" + Unix: "$XDG_STATE_HOME/nvim/shada/main.shada" + Windows: "$XDG_STATE_HOME/nvim-data/shada/main.shada" See also |base-directories|. - To choose a different file name you can use: - The "n" flag in the 'shada' option. @@ -1067,55 +1067,55 @@ however that this means everything will be overwritten with information from the first Vim, including the command line history, etc. The ShaDa file itself can be edited by hand too, although we suggest you -start with an existing one to get the format right. You need to understand -MessagePack (or, more likely, find software that is able to use it) format to -do this. This can be useful in order to create a second file, say -"~/.my.shada" which could contain certain settings that you always want when -you first start Neovim. For example, you can preload registers with -particular data, or put certain commands in the command line history. A line +start with an existing one to get the format right. You need to understand +MessagePack (or, more likely, find software that is able to use it) format to +do this. This can be useful in order to create a second file, say +"~/.my.shada" which could contain certain settings that you always want when +you first start Neovim. For example, you can preload registers with +particular data, or put certain commands in the command line history. A line in your |config| file like > :rshada! ~/.my.shada -can be used to load this information. You could even have different ShaDa -files for different types of files (e.g., C code) and load them based on the -file name, using the ":autocmd" command (see |:autocmd|). More information on +can be used to load this information. You could even have different ShaDa +files for different types of files (e.g., C code) and load them based on the +file name, using the ":autocmd" command (see |:autocmd|). More information on ShaDa file format is contained in |shada-format| section. *E136* *E929* *shada-error-handling* -Some errors make Neovim leave temporary file named `{basename}.tmp.X` (X is -any free letter from `a` to `z`) while normally it will create this file, -write to it and then rename `{basename}.tmp.X` to `{basename}`. Such errors +Some errors make Neovim leave temporary file named `{basename}.tmp.X` (X is +any free letter from `a` to `z`) while normally it will create this file, +write to it and then rename `{basename}.tmp.X` to `{basename}`. Such errors include: -- Errors which make Neovim think that read file is not a ShaDa file at all: - non-ShaDa files are not overwritten for safety reasons to avoid accidentally - destroying an unrelated file. This could happen e.g. when typing "nvim -i - file" in place of "nvim -R file" (yes, somebody did that at least with Vim). +- Errors which make Neovim think that read file is not a ShaDa file at all: + non-ShaDa files are not overwritten for safety reasons to avoid accidentally + destroying an unrelated file. This could happen e.g. when typing "nvim -i + file" in place of "nvim -R file" (yes, somebody did that at least with Vim). Such errors are listed at |shada-critical-contents-errors|. -- If writing to the temporary file failed: e.g. because of the insufficient +- If writing to the temporary file failed: e.g. because of the insufficient space left. - If renaming file failed: e.g. because of insufficient permissions. -- If target ShaDa file has different from the Neovim instance's owners (user - and group) and changing them failed. Unix-specific, applies only when +- If target ShaDa file has different from the Neovim instance's owners (user + and group) and changing them failed. Unix-specific, applies only when Neovim was launched from root. -Do not forget to remove the temporary file or replace the target file with -temporary one after getting one of the above errors or all attempts to create -a ShaDa file may fail with |E929|. If you got one of them when using -|:wshada| (and not when exiting Neovim: i.e. when you have Neovim session +Do not forget to remove the temporary file or replace the target file with +temporary one after getting one of the above errors or all attempts to create +a ShaDa file may fail with |E929|. If you got one of them when using +|:wshada| (and not when exiting Neovim: i.e. when you have Neovim session running) you have additional options: -- First thing which you should consider if you got any error, except failure - to write to the temporary file: remove existing file and replace it with the +- First thing which you should consider if you got any error, except failure + to write to the temporary file: remove existing file and replace it with the temporary file. Do it even if you have running Neovim instance. -- Fix the permissions and/or file ownership, free some space and attempt to +- Fix the permissions and/or file ownership, free some space and attempt to write again. Do not remove the existing file. -- Use |:wshada| with bang. Does not help in case of permission error. If - target file was actually the ShaDa file some information may be lost in this - case. To make the matters slightly better use |:rshada| prior to writing, - but this still will loose buffer-local marks and change list entries for any +- Use |:wshada| with bang. Does not help in case of permission error. If + target file was actually the ShaDa file some information may be lost in this + case. To make the matters slightly better use |:rshada| prior to writing, + but this still will loose buffer-local marks and change list entries for any file which is not opened in the current Neovim instance. -- Remove the target file from shell and use |:wshada|. Consequences are not - different from using |:wshada| with bang, but "rm -f" works in some cases +- Remove the target file from shell and use |:wshada|. Consequences are not + different from using |:wshada| with bang, but "rm -f" works in some cases when you don't have write permissions. *:rsh* *:rshada* *E886* @@ -1129,13 +1129,13 @@ running) you have additional options: The information in the file is first read in to make a merge between old and new info. When [!] is used, the old information is not read first, only the - internal info is written (also disables safety checks - described in |shada-error-handling|). If 'shada' is + internal info is written (also disables safety checks + described in |shada-error-handling|). If 'shada' is empty, marks for up to 100 files will be written. - When you get error "E929: All .tmp.X files exist, - cannot write ShaDa file!" check that no old temp files - were left behind (e.g. - ~/.local/share/nvim/shada/main.shada.tmp*). + When you get error "E929: All .tmp.X files exist, + cannot write ShaDa file!" check that no old temp files + were left behind (e.g. + ~/.local/state/nvim/shada/main.shada.tmp*). Note: Executing :wshada will reset all |'quote| marks. @@ -1158,82 +1158,82 @@ running) you have additional options: SHADA FILE FORMAT *shada-format* -ShaDa files are concats of MessagePack entries. Each entry is a concat of +ShaDa files are concats of MessagePack entries. Each entry is a concat of exactly four MessagePack objects: -1. First goes type of the entry. Object type must be an unsigned integer. +1. First goes type of the entry. Object type must be an unsigned integer. Object type must not be equal to zero. 2. Second goes entry timestamp. It must also be an unsigned integer. -3. Third goes the length of the fourth entry. Unsigned integer as well, used +3. Third goes the length of the fourth entry. Unsigned integer as well, used for fast skipping without parsing. -4. Fourth is actual entry data. All currently used ShaDa entries use - containers to hold data: either map or array. All string values in those - containers are either binary (applies to filenames) or UTF-8, yet parser +4. Fourth is actual entry data. All currently used ShaDa entries use + containers to hold data: either map or array. All string values in those + containers are either binary (applies to filenames) or UTF-8, yet parser needs to expect that invalid bytes may be present in a UTF-8 string. Exact format depends on the entry type: Entry type (name) Entry data ~ - 1 (Header) Map containing data that describes the generator - instance that wrote this ShaDa file. It is ignored + 1 (Header) Map containing data that describes the generator + instance that wrote this ShaDa file. It is ignored when reading ShaDa files. Contains the following data: Key Data ~ - generator Binary, software used to generate ShaDa - file. Is equal to "nvim" when ShaDa file was + generator Binary, software used to generate ShaDa + file. Is equal to "nvim" when ShaDa file was written by Neovim. version Binary, generator version. encoding Binary, effective 'encoding' value. max_kbyte Integer, effective |shada-s| limit value. pid Integer, instance process ID. - * It is allowed to have any number of + * It is allowed to have any number of additional keys with any data. - 2 (SearchPattern) Map containing data describing last used search or - substitute pattern. Normally ShaDa file contains two - such entries: one with "ss" key set to true (describes - substitute pattern, see |:substitute|), and one set to - false (describes search pattern, see - |search-commands|). "su" key should be true on one of - the entries. If key value is equal to default then it + 2 (SearchPattern) Map containing data describing last used search or + substitute pattern. Normally ShaDa file contains two + such entries: one with "ss" key set to true (describes + substitute pattern, see |:substitute|), and one set to + false (describes search pattern, see + |search-commands|). "su" key should be true on one of + the entries. If key value is equal to default then it is normally not present. Keys: Key Type Default Description ~ sm Boolean true Effective 'magic' value. sc Boolean false Effective 'smartcase' value. - sl Boolean true True if search pattern comes - with a line offset. See + sl Boolean true True if search pattern comes + with a line offset. See |search-offset|. - se Boolean false True if |search-offset| - requested to place cursor at - (relative to) the end of the + se Boolean false True if |search-offset| + requested to place cursor at + (relative to) the end of the pattern. so Integer 0 Offset value. |search-offset| - su Boolean false True if current entry was the + su Boolean false True if current entry was the last used search pattern. - ss Boolean false True if current entry describes + ss Boolean false True if current entry describes |:substitute| pattern. sh Boolean false True if |v:hlsearch| is on. - With |shada-h| or 'nohlsearch' + With |shada-h| or 'nohlsearch' this key is always false. sp Binary N/A Actual pattern. Required. - sb Boolean false True if search direction is + sb Boolean false True if search direction is backward. - * any none Other keys are allowed for - compatibility reasons, see + * any none Other keys are allowed for + compatibility reasons, see |shada-compatibility|. - 3 (SubString) Array containing last |:substitute| replacement string. - Contains single entry: binary, replacement string used. - More entries are allowed for compatibility reasons, see + 3 (SubString) Array containing last |:substitute| replacement string. + Contains single entry: binary, replacement string used. + More entries are allowed for compatibility reasons, see |shada-compatibility|. - 4 (HistoryEntry) Array containing one entry from history. Should have - two or three entries. First one is history type - (unsigned integer), second is history line (binary), - third is the separator character (unsigned integer, - must be in interval [0, 255]). Third item is only - valid for search history. Possible history types are - listed in |hist-names|, here are the corresponding - numbers: 0 - cmd, 1 - search, 2 - expr, 3 - input, + 4 (HistoryEntry) Array containing one entry from history. Should have + two or three entries. First one is history type + (unsigned integer), second is history line (binary), + third is the separator character (unsigned integer, + must be in interval [0, 255]). Third item is only + valid for search history. Possible history types are + listed in |hist-names|, here are the corresponding + numbers: 0 - cmd, 1 - search, 2 - expr, 3 - input, 4 - debug. - 5 (Register) Map describing one register (|registers|). If key - value is equal to default then it is normally not + 5 (Register) Map describing one register (|registers|). If key + value is equal to default then it is normally not present. Keys: Key Type Def Description ~ rt UInteger 0 Register type: @@ -1261,12 +1261,12 @@ exactly four MessagePack objects: * any none Other keys are allowed for compatibility reasons, see |shada-compatibility|. - 6 (Variable) Array containing two items: variable name (binary) and - variable value (any object). Values are converted - using the same code |msgpackparse()| uses when reading, - |msgpackdump()| when writing, so there may appear - |msgpack-special-dict|s. If there are more then two - entries then the rest are ignored + 6 (Variable) Array containing two items: variable name (binary) and + variable value (any object). Values are converted + using the same code |msgpackparse()| uses when reading, + |msgpackdump()| when writing, so there may appear + |msgpack-special-dict|s. If there are more then two + entries then the rest are ignored (|shada-compatibility|). 7 (GlobalMark) 8 (Jump) @@ -1280,57 +1280,57 @@ exactly four MessagePack objects: Data contained in the map: Key Type Default Description ~ - l UInteger 1 Position line number. Must be + l UInteger 1 Position line number. Must be greater then zero. c UInteger 0 Position column number. - n UInteger 34 ('"') Mark name. Only valid for - GlobalMark and LocalMark + n UInteger 34 ('"') Mark name. Only valid for + GlobalMark and LocalMark entries. f Binary N/A File name. Required. - * any none Other keys are allowed for - compatibility reasons, see + * any none Other keys are allowed for + compatibility reasons, see |shada-compatibility|. - 9 (BufferList) Array containing maps. Each map in the array + 9 (BufferList) Array containing maps. Each map in the array represents one buffer. Possible keys: Key Type Default Description ~ - l UInteger 1 Position line number. Must be + l UInteger 1 Position line number. Must be greater then zero. c UInteger 0 Position column number. f Binary N/A File name. Required. - * any none Other keys are allowed for - compatibility reasons, see + * any none Other keys are allowed for + compatibility reasons, see |shada-compatibility|. - * (Unknown) Any other entry type is allowed for compatibility + * (Unknown) Any other entry type is allowed for compatibility reasons, see |shada-compatibility|. *E575* *E576* -Errors in ShaDa file may have two types: E575 used for all “logical” errors -and E576 used for all “critical” errors. Critical errors trigger behaviour -described in |shada-error-handling| when writing and skipping the rest of the +Errors in ShaDa file may have two types: E575 used for all “logical” errors +and E576 used for all “critical” errors. Critical errors trigger behaviour +described in |shada-error-handling| when writing and skipping the rest of the file when reading and include: *shada-critical-contents-errors* - Any of first three MessagePack objects being not an unsigned integer. -- Third object requesting amount of bytes greater then bytes left in the ShaDa +- Third object requesting amount of bytes greater then bytes left in the ShaDa file. - Entry with zero type. I.e. first object being equal to zero. - MessagePack parser failing to parse the entry data. -- MessagePack parser consuming less or requesting greater bytes then described - in the third object for parsing fourth object. I.e. when fourth object - either contains more then one MessagePack object or it does not contain +- MessagePack parser consuming less or requesting greater bytes then described + in the third object for parsing fourth object. I.e. when fourth object + either contains more then one MessagePack object or it does not contain complete MessagePack object. ============================================================================== Standard Paths *standard-path* -Nvim stores configuration, data, and logs in standard locations. Plugins are -strongly encouraged to follow this pattern also. Use |stdpath()| to get the +Nvim stores configuration, data, and logs in standard locations. Plugins are +strongly encouraged to follow this pattern also. Use |stdpath()| to get the paths. *base-directories* *xdg* The "base" (root) directories conform to the XDG Base Directory Specification. https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html -The $XDG_CONFIG_HOME and $XDG_DATA_HOME environment variables are used if they -exist, otherwise default values (listed below) are used. +The $XDG_CONFIG_HOME, $XDG_DATA_HOME and $XDG_STATE_HOME environment variables +are used if they exist, otherwise default values (listed below) are used. CONFIG DIRECTORY (DEFAULT) ~ *$XDG_CONFIG_HOME* Nvim: stdpath("config") @@ -1342,6 +1342,11 @@ DATA DIRECTORY (DEFAULT) ~ Unix: ~/.local/share ~/.local/share/nvim Windows: ~/AppData/Local ~/AppData/Local/nvim-data +STATE DIRECTORY (DEFAULT) ~ + *$XDG_STATE_HOME* Nvim: stdpath("state") + Unix: ~/.local/state ~/.local/state/nvim + Windows: ~/AppData/Local ~/AppData/Local/nvim-data + Note: Throughout the user manual these defaults are used as placeholders, e.g. "~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config". @@ -1349,7 +1354,7 @@ LOG FILE *$NVIM_LOG_FILE* Besides 'debug' and 'verbose', Nvim keeps a general log file for internal debugging, plugins and RPC clients. > :echo $NVIM_LOG_FILE -By default, the file is located at stdpath('cache')/log unless that path +By default, the file is located at stdpath('log')/log unless that path is inaccessible or if $NVIM_LOG_FILE was set before |startup|. diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index 2a78d975ee..c3ad704bb7 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -453,7 +453,7 @@ your own highlight colors for the progress bar. Example: > hi TOhtmlProgress guifg=#c0ffee ctermbg=7 < *g:html_number_lines* -Default: current 'number' setting. +Default: Current 'number' setting. When 0, buffer text is displayed in the generated HTML without line numbering. When 1, a column of line numbers is added to the generated HTML with the same highlighting as the line number column in Vim (|hl-LineNr|). @@ -542,7 +542,7 @@ folded text will open the fold as if |g:html_hover_unfold| were set. :let g:html_no_foldcolumn = 1 < *TOhtml-uncopyable-text* *g:html_prevent_copy* -Default: empty string. +Default: Empty string. This option prevents certain regions of the generated HTML from being copied, when you select all text in document rendered in a browser and copy it. Useful for allowing users to copy-paste only the source text even if a fold column or @@ -568,7 +568,7 @@ uncopyable regions. In some browsers, especially older browsers, after selecting an entire page and copying the selection, the <input> tags are not pasted with the page text. If |g:html_no_invalid| is 0, the <input> tags have invalid type; this works in more browsers, but the page will not validate. -Note: this method does NOT work in recent versions of Chrome and equivalent +Note: This method does NOT work in recent versions of Chrome and equivalent browsers; the <input> tags get pasted with the text. When "fallback" (default value), the same <input> elements are generated for @@ -624,12 +624,12 @@ To append a string "_mystring" to the end of each ID: > :let g:html_id_expr = '"_mystring"' < -Note, when converting a diff view to HTML, the expression will only be +Note: When converting a diff view to HTML, the expression will only be evaluated for the first window in the diff, and the result used for all the windows. *TOhtml-wrap-text* *g:html_pre_wrap* -Default: current 'wrap' setting. +Default: Current 'wrap' setting. When 0, if |g:html_no_pre| is 0 or unset, the text in the generated HTML does not wrap at the edge of the browser window. When 1, if |g:html_use_css| is 1, the CSS 2.0 "white-space:pre-wrap" value is @@ -689,7 +689,7 @@ wide browser support. However, you can override this to support specific encodings that may not be automatically detected by default (see options below). See http://www.iana.org/assignments/character-sets for the IANA names. -Note, by default all Unicode encodings are converted to UTF-8 with no BOM in +Note: By default all Unicode encodings are converted to UTF-8 with no BOM in the generated HTML, as recommended by W3C: http://www.w3.org/International/questions/qa-choosing-encodings @@ -1293,8 +1293,8 @@ the global or buffer-local variable load_doxygen_syntax. This is done by adding the following to your vimrc. > :let g:load_doxygen_syntax=1 -There are a couple of variables that have an effect on syntax highlighting, and -are to do with non-standard highlighting options. +There are a couple of variables that have an effect on syntax highlighting, +and are to do with non-standard highlighting options. Variable Default Effect ~ g:doxygen_enhanced_color @@ -1436,8 +1436,8 @@ To enable highlighting some special atoms, put this in your vimrc: > ELIXIR *elixir.vim* *ft-elixir-syntax* -Elixir is a dynamic, functional language for building scalable and maintainable -applications. +Elixir is a dynamic, functional language for building scalable and +maintainable applications. The following file extensions are auto-detected as Elixir file types: @@ -1453,7 +1453,7 @@ Elixir. FLEXWIKI *flexwiki.vim* *ft-flexwiki-syntax* FlexWiki is an ASP.NET-based wiki package available at http://www.flexwiki.com -NOTE: this site currently doesn't work, on Wikipedia is mentioned that +NOTE: This site currently doesn't work, on Wikipedia is mentioned that development stopped in 2009. Syntax highlighting is available for the most common elements of FlexWiki @@ -1533,8 +1533,8 @@ syntax highlighting will not be correct if the form is incorrectly set. When you create a new fortran file, the syntax script assumes fixed source form. If you always use free source form, then > :let fortran_free_source=1 -in your vimrc prior to the :syntax on command. If you always use fixed source -form, then > +in your vimrc prior to the :syntax on command. If you always use fixed +source form, then > :let fortran_fixed_source=1 in your vimrc prior to the :syntax on command. @@ -1807,8 +1807,8 @@ ends with -->) you can define > JavaScript and Visual Basic embedded inside HTML documents are highlighted as 'Special' with statements, comments, strings and so on colored as in standard -programming languages. Note that only JavaScript and Visual Basic are currently -supported, no other scripting language has been added yet. +programming languages. Note that only JavaScript and Visual Basic are +currently supported, no other scripting language has been added yet. Embedded and inlined cascading style sheets (CSS) are highlighted too. @@ -1912,8 +1912,8 @@ The java.vim syntax highlighting file offers several options: In Java 1.0.2 it was never possible to have braces inside parens, so this was flagged as an error. Since Java 1.1 this is possible (with anonymous -classes), and therefore is no longer marked as an error. If you prefer the old -way, put the following line into your vim startup file: > +classes), and therefore is no longer marked as an error. If you prefer the +old way, put the following line into your vim startup file: > :let java_mark_braces_in_parens_as_errors=1 All identifiers in java.lang.* are always visible in all classes. To @@ -2031,10 +2031,10 @@ LISP *lisp.vim* *ft-lisp-syntax* The lisp syntax highlighting provides two options: > - g:lisp_instring : if it exists, then "(...)" strings are highlighted + g:lisp_instring : If it exists, then "(...)" strings are highlighted as if the contents of the string were lisp. Useful for AutoLisp. - g:lisp_rainbow : if it exists and is nonzero, then differing levels + g:lisp_rainbow : If it exists and is nonzero, then differing levels of parenthesization will receive different highlighting. < @@ -2440,8 +2440,8 @@ If you do not want complex things like '@{${"foo"}}' to be parsed: > (In Vim 6.x it was the other way around: "perl_extended_vars" enabled it.) -The coloring strings can be changed. By default strings and qq friends will be -highlighted like the first line. If you set the variable +The coloring strings can be changed. By default strings and qq friends will +be highlighted like the first line. If you set the variable perl_string_as_statement, it will be highlighted as in the second line. "hello world!"; qq|hello world|; @@ -2453,8 +2453,8 @@ perl_string_as_statement, it will be highlighted as in the second line. The syncing has 3 options. The first two switch off some triggering of synchronization and should only be needed in case it fails to work properly. If while scrolling all of a sudden the whole screen changes color completely -then you should try and switch off one of those. Let me know if you can figure -out the line that causes the mistake. +then you should try and switch off one of those. Let me know if you can +figure out the line that causes the mistake. One triggers on "^\s*sub\s*" and the other on "^[$@%]" more or less. > @@ -2491,7 +2491,7 @@ behavior, set 'perl_nofold_packages': > PHP3 and PHP4 *php.vim* *php3.vim* *ft-php-syntax* *ft-php3-syntax* -[note: previously this was called "php3", but since it now also supports php4 +[Note: Previously this was called "php3", but since it now also supports php4 it has been renamed to "php"] There are the following options for the php syntax highlighting. @@ -2561,15 +2561,15 @@ PPWizard is a preprocessor for HTML and OS/2 INF files This syntax file has the options: -- ppwiz_highlight_defs : determines highlighting mode for PPWizard's +- ppwiz_highlight_defs : Determines highlighting mode for PPWizard's definitions. Possible values are ppwiz_highlight_defs = 1 : PPWizard #define statements retain the - colors of their contents (e.g. PPWizard macros and variables) + colors of their contents (e.g. PPWizard macros and variables). - ppwiz_highlight_defs = 2 : preprocessor #define and #evaluate + ppwiz_highlight_defs = 2 : Preprocessor #define and #evaluate statements are shown in a single color with the exception of line - continuation symbols + continuation symbols. The default setting for ppwiz_highlight_defs is 1. @@ -2608,7 +2608,7 @@ highlighted by defining the postscr_level variable as follows: > If this variable is not defined it defaults to 2 (level 2) since this is the most prevalent version currently. -Note, not all PS interpreters will support all language features for a +Note: Not all PS interpreters will support all language features for a particular language level. In particular the %!PS-Adobe-3.0 at the start of PS files does NOT mean the PostScript present is level 3 PostScript! @@ -2710,7 +2710,7 @@ If you want all possible Python highlighting (the same as setting the preceding last option and unsetting all other ones): > :let python_highlight_all = 1 -Note: only existence of these options matter, not their value. You can replace +Note: Only existence of these options matter, not their value. You can replace 1 above with anything. QUAKE *quake.vim* *ft-quake-syntax* @@ -3150,16 +3150,16 @@ The Speedup syntax file has some options: the DECLARE section; if you defined own types, you have to include them in the syntax file. -- oneline_comments : this value ranges from 1 to 3 and determines the +- oneline_comments : This value ranges from 1 to 3 and determines the highlighting of # style comments. - oneline_comments = 1 : allow normal Speedup code after an even + oneline_comments = 1 : Allow normal Speedup code after an even number of #s. - oneline_comments = 2 : show code starting with the second # as + oneline_comments = 2 : Show code starting with the second # as error. This is the default setting. - oneline_comments = 3 : show the whole line as error if it contains + oneline_comments = 3 : Show the whole line as error if it contains more than one #. Since especially OPERATION sections tend to become very large due to @@ -3198,8 +3198,8 @@ This covers the shell named "tcsh". It is a superset of csh. See |csh.vim| for how the filetype is detected. Tcsh does not allow \" in strings unless the "backslash_quote" shell variable -is set. If you want VIM to assume that no backslash quote constructs exist add -this line to your vimrc: > +is set. If you want VIM to assume that no backslash quote constructs exist +add this line to your vimrc: > :let tcsh_backslash_quote = 0 @@ -3552,7 +3552,7 @@ start and end tags. This can be turned on by > :let g:xml_syntax_folding = 1 :set foldmethod=syntax -Note: syntax folding might slow down syntax highlighting significantly, +Note: Syntax folding might slow down syntax highlighting significantly, especially for large files. @@ -4982,8 +4982,8 @@ ctermbg={color-nr} *highlight-ctermbg* a number instead of a color name. Note that for 16 color ansi style terminals (including xterms), the - numbers in the NR-8 column is used. Here '*' means 'add 8' so that Blue - is 12, DarkGray is 8 etc. + numbers in the NR-8 column is used. Here '*' means 'add 8' so that + Blue is 12, DarkGray is 8 etc. Note that for some color terminals these names may result in the wrong colors! @@ -5096,56 +5096,56 @@ These are the builtin highlighting groups. Note that the highlighting depends on the value of 'background'. You can see the current settings with the ":highlight" command. *hl-ColorColumn* -ColorColumn used for the columns set with 'colorcolumn' +ColorColumn Used for the columns set with 'colorcolumn'. *hl-Conceal* -Conceal placeholder characters substituted for concealed - text (see 'conceallevel') +Conceal Placeholder characters substituted for concealed + text (see 'conceallevel'). *hl-CurSearch* -CurSearch used for highlighting a search pattern under the cursor - (see 'hlsearch') +CurSearch Used for highlighting a search pattern under the cursor + (see 'hlsearch'). *hl-Cursor* -Cursor character under the cursor -lCursor the character under the cursor when |language-mapping| - is used (see 'guicursor') +Cursor Character under the cursor. +lCursor Character under the cursor when |language-mapping| + is used (see 'guicursor'). *hl-CursorIM* -CursorIM like Cursor, but used when in IME mode |CursorIM| +CursorIM Like Cursor, but used when in IME mode. |CursorIM| *hl-CursorColumn* CursorColumn Screen-column at the cursor, when 'cursorcolumn' is set. *hl-CursorLine* CursorLine Screen-line at the cursor, when 'cursorline' is set. Low-priority if foreground (ctermfg OR guifg) is not set. *hl-Directory* -Directory directory names (and other special names in listings) +Directory Directory names (and other special names in listings). *hl-DiffAdd* -DiffAdd diff mode: Added line |diff.txt| +DiffAdd Diff mode: Added line. |diff.txt| *hl-DiffChange* -DiffChange diff mode: Changed line |diff.txt| +DiffChange Diff mode: Changed line. |diff.txt| *hl-DiffDelete* -DiffDelete diff mode: Deleted line |diff.txt| +DiffDelete Diff mode: Deleted line. |diff.txt| *hl-DiffText* -DiffText diff mode: Changed text within a changed line |diff.txt| +DiffText Diff mode: Changed text within a changed line. |diff.txt| *hl-EndOfBuffer* -EndOfBuffer filler lines (~) after the end of the buffer. +EndOfBuffer Filler lines (~) after the end of the buffer. By default, this is highlighted like |hl-NonText|. *hl-TermCursor* -TermCursor cursor in a focused terminal +TermCursor Cursor in a focused terminal. *hl-TermCursorNC* -TermCursorNC cursor in an unfocused terminal +TermCursorNC Cursor in an unfocused terminal. *hl-ErrorMsg* -ErrorMsg error messages on the command line +ErrorMsg Error messages on the command line. *hl-WinSeparator* -WinSeparator separators between window splits +WinSeparator Separators between window splits. *hl-Folded* -Folded line used for closed folds +Folded Line used for closed folds. *hl-FoldColumn* FoldColumn 'foldcolumn' *hl-SignColumn* -SignColumn column where |signs| are displayed +SignColumn Column where |signs| are displayed. *hl-IncSearch* IncSearch 'incsearch' highlighting; also used for the text replaced with - ":s///c" + ":s///c". *hl-Substitute* -Substitute |:substitute| replacement text highlighting +Substitute |:substitute| replacement text highlighting. *hl-LineNr* LineNr Line number for ":number" and ":#" commands, and when 'number' @@ -5164,15 +5164,15 @@ CursorLineSign Like SignColumn when 'cursorline' is set for the cursor line. *hl-CursorLineFold* CursorLineFold Like FoldColumn when 'cursorline' is set for the cursor line. *hl-MatchParen* -MatchParen The character under the cursor or just before it, if it +MatchParen Character under the cursor or just before it, if it is a paired bracket, and its match. |pi_paren.txt| *hl-ModeMsg* -ModeMsg 'showmode' message (e.g., "-- INSERT --") +ModeMsg 'showmode' message (e.g., "-- INSERT --"). *hl-MsgArea* -MsgArea Area for messages and cmdline +MsgArea Area for messages and cmdline. *hl-MsgSeparator* -MsgSeparator Separator for scrolled messages, `msgsep` flag of 'display' +MsgSeparator Separator for scrolled messages, `msgsep` flag of 'display'. *hl-MoreMsg* MoreMsg |more-prompt| *hl-NonText* @@ -5181,21 +5181,21 @@ NonText '@' at the end of the window, characters from 'showbreak' (e.g., ">" displayed when a double-wide character doesn't fit at the end of the line). See also |hl-EndOfBuffer|. *hl-Normal* -Normal normal text +Normal Normal text. *hl-NormalFloat* NormalFloat Normal text in floating windows. *hl-NormalNC* -NormalNC normal text in non-current windows +NormalNC Normal text in non-current windows. *hl-Pmenu* -Pmenu Popup menu: normal item. +Pmenu Popup menu: Normal item. *hl-PmenuSel* -PmenuSel Popup menu: selected item. +PmenuSel Popup menu: Selected item. *hl-PmenuSbar* -PmenuSbar Popup menu: scrollbar. +PmenuSbar Popup menu: Scrollbar. *hl-PmenuThumb* PmenuThumb Popup menu: Thumb of the scrollbar. *hl-Question* -Question |hit-enter| prompt and yes/no questions +Question |hit-enter| prompt and yes/no questions. *hl-QuickFixLine* QuickFixLine Current |quickfix| item in the quickfix window. Combined with |hl-CursorLine| when the cursor is there. @@ -5203,7 +5203,7 @@ QuickFixLine Current |quickfix| item in the quickfix window. Combined with Search Last search pattern highlighting (see 'hlsearch'). Also used for similar items that need to stand out. *hl-SpecialKey* -SpecialKey Unprintable characters: text displayed differently from what +SpecialKey Unprintable characters: Text displayed differently from what it really is. But not 'listchars' whitespace. |hl-Whitespace| *hl-SpellBad* SpellBad Word that is not recognized by the spellchecker. |spell| @@ -5220,30 +5220,34 @@ SpellRare Word that is recognized by the spellchecker as one that is hardly ever used. |spell| Combined with the highlighting used otherwise. *hl-StatusLine* -StatusLine status line of current window +StatusLine Status line of current window. *hl-StatusLineNC* -StatusLineNC status lines of not-current windows - Note: if this is equal to "StatusLine" Vim will use "^^^" in +StatusLineNC Status lines of not-current windows. + Note: If this is equal to "StatusLine", Vim will use "^^^" in the status line of the current window. *hl-TabLine* -TabLine tab pages line, not active tab page label +TabLine Tab pages line, not active tab page label. *hl-TabLineFill* -TabLineFill tab pages line, where there are no labels +TabLineFill Tab pages line, where there are no labels. *hl-TabLineSel* -TabLineSel tab pages line, active tab page label +TabLineSel Tab pages line, active tab page label. *hl-Title* -Title titles for output from ":set all", ":autocmd" etc. +Title Titles for output from ":set all", ":autocmd" etc. *hl-Visual* -Visual Visual mode selection +Visual Visual mode selection. *hl-VisualNOS* VisualNOS Visual mode selection when vim is "Not Owning the Selection". *hl-WarningMsg* -WarningMsg warning messages +WarningMsg Warning messages. *hl-Whitespace* Whitespace "nbsp", "space", "tab", "multispace", "lead" and "trail" - in 'listchars' + in 'listchars'. *hl-WildMenu* -WildMenu current match in 'wildmenu' completion +WildMenu Current match in 'wildmenu' completion. + *hl-WinBar* +WinBar Window bar of current window. + *hl-WinBarNC* +WinBarNC Window bar of not-current windows. *hl-User1* *hl-User1..9* *hl-User9* The 'statusline' syntax allows the use of 9 different highlights in the diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index c3aa83465c..339ae0c2ed 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -472,8 +472,8 @@ parse_query({lang}, {query}) *parse_query()* • `info.patterns` contains information about predicates. Parameters: ~ - {lang} string The language - {query} string A string containing the query (s-expr + {lang} (string) The language + {query} (string) A string containing the query (s-expr syntax) Return: ~ @@ -702,7 +702,7 @@ LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()* Registers callbacks for the parser. Parameters: ~ - {cbs} table An |nvim_buf_attach()|-like table argument + {cbs} (table) An |nvim_buf_attach()|-like table argument with the following keys : • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback. diff --git a/runtime/doc/usr_21.txt b/runtime/doc/usr_21.txt index 44d653a1a7..add5d48073 100644 --- a/runtime/doc/usr_21.txt +++ b/runtime/doc/usr_21.txt @@ -352,12 +352,12 @@ another session. this yourself then. Example: > :mksession! ~/.config/nvim/secret.vim - :wshada! ~/.local/share/nvim/shada/secret.shada + :wshada! ~/.local/state/nvim/shada/secret.shada And to restore this again: > :source ~/.config/nvim/secret.vim - :rshada! ~/.local/share/nvim/shada/secret.shada + :rshada! ~/.local/state/nvim/shada/secret.shada ============================================================================== *21.5* Views diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 75ee0fdfdf..0a25904104 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -30,10 +30,10 @@ CTRL-L Clears and redraws the screen. The redraw may happen function (or a mapping if 'lazyredraw' set). *:redraws* *:redrawstatus* -:redraws[tatus][!] Redraws the status line of the current window, or all - status lines if "!" is included. - Useful if 'statusline' includes an item that doesn't - cause automatic updating. +:redraws[tatus][!] Redraws the status line and window bar of the current + window, or all status lines and window bars if "!" is + included. Useful if 'statusline' or 'winbar' includes + an item that doesn't cause automatic updating. *:redrawt* *:redrawtabline* :redrawt[abline] Redraw the tabline. Useful to update the tabline when diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index e24dd46f49..c926337b47 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -17,7 +17,7 @@ centralized reference of the differences. - Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|. - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files. -- Use `$XDG_DATA_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent +- Use `$XDG_STATE_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent session information. |shada| ============================================================================== @@ -32,12 +32,12 @@ centralized reference of the differences. - 'autoread' is enabled - 'background' defaults to "dark" (unless set automatically by the terminal/UI) - 'backspace' defaults to "indent,eol,start" -- 'backupdir' defaults to .,~/.local/share/nvim/backup// (|xdg|), auto-created +- 'backupdir' defaults to .,~/.local/state/nvim/backup// (|xdg|), auto-created - 'belloff' defaults to "all" - 'compatible' is always disabled - 'complete' excludes "i" - 'cscopeverbose' is enabled -- 'directory' defaults to ~/.local/share/nvim/swap// (|xdg|), auto-created +- 'directory' defaults to ~/.local/state/nvim/swap// (|xdg|), auto-created - 'display' defaults to "lastline,msgsep" - 'encoding' is UTF-8 (cf. 'fileencoding' for file-content encoding) - 'fillchars' defaults (in effect) to "vert:│,fold:·,sep:│" @@ -65,7 +65,7 @@ centralized reference of the differences. - 'tags' defaults to "./tags;,tags" - 'ttimeoutlen' defaults to 50 - 'ttyfast' is always set -- 'undodir' defaults to ~/.local/share/nvim/undo// (|xdg|), auto-created +- 'undodir' defaults to ~/.local/state/nvim/undo// (|xdg|), auto-created - 'viewoptions' includes "unix,slash", excludes "options" - 'viminfo' includes "!" - 'wildmenu' is enabled @@ -87,6 +87,8 @@ of these in your config by simply removing the mapping, e.g. ":unmap Y". nnoremap <C-L> <Cmd>nohlsearch<Bar>diffupdate<Bar>normal! <C-L><CR> inoremap <C-U> <C-G>u<C-U> inoremap <C-W> <C-G>u<C-W> + xnoremap * y/\V<C-R>"<CR> + xnoremap # y?\V<C-R>"<CR> < Default Autocommands ~ *default-autocmds* @@ -366,9 +368,8 @@ Macro/|recording| behavior the results of keys from 'keymap'. Mappings: -- Creating a mapping for a simplifiable key (e.g. <C-I>) doesn't replace an + Creating a mapping for a simplifiable key (e.g. <C-I>) doesn't replace an existing mapping for its simplified form (e.g. <Tab>). -- The rhs of a mapping is not simplified when it is defined. Motion: The |jumplist| avoids useless/phantom jumps. @@ -547,11 +548,13 @@ Options: 'maxmemtot' Nvim delegates memory-management to the OS. 'maxcombine' (6 is always used) *'prompt'* *'noprompt'* + *'remap'* *'noremap'* *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'* 'shelltype' *'shortname'* *'sn'* *'noshortname'* *'nosn'* *'swapsync'* *'sws'* *'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows) + *'terse'* *'noterse'* (Add "s" to 'shortmess' instead) 'textauto' 'textmode' *'toolbar'* *'tb'* diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index cd5425336f..8062b9e28f 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -983,7 +983,7 @@ modified, but is forced (with '!') to be removed from a window, and 'autowrite' is off or the buffer can't be written. You can make a hidden buffer not hidden by starting to edit it with any -command. Or by deleting it with the ":bdelete" command. +command, or by deleting it with the ":bdelete" command. The 'hidden' is global, it is used for all buffers. The 'bufhidden' option can be used to make an exception for a specific buffer. It can take these |