diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 171 |
1 files changed, 126 insertions, 45 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| |