diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 495 |
1 files changed, 286 insertions, 209 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ba3b7c0915..87269ad147 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -579,7 +579,7 @@ created for extmark changes. ============================================================================== Global Functions *api-global* -nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* +nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()* Find files in runtime directories Attributes: ~ @@ -700,6 +700,21 @@ nvim_chan_send({chan}, {data}) *nvim_chan_send()* • {chan} id of the channel • {data} data to write. 8-bit clean: can contain NUL bytes. +nvim_complete_set({index}, {opts}) *nvim_complete_set()* + Set info for the completion candidate index. if the info was shown in a + window, then the window and buffer ids are returned for further + customization. If the text was not shown, an empty dict is returned. + + Parameters: ~ + • {index} the completion candidate index + • {opts} Optional parameters. + • info: (string) info text. + + Return: ~ + Dictionary containing these keys: + • winid: (number) floating window id + • bufnr: (number) buffer id in floating window + nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Creates a new, empty, unnamed buffer. @@ -751,13 +766,13 @@ nvim_del_var({name}) *nvim_del_var()* Parameters: ~ • {name} Variable name -nvim_echo({chunks}, {history}, {*opts}) *nvim_echo()* +nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* Echo a message. Parameters: ~ - • {chunks} A list of [text, hl_group] arrays, each representing a text - chunk with specified highlight. `hl_group` element can be - omitted for no highlight. + • {chunks} A list of `[text, hl_group]` arrays, each representing a + text chunk with specified highlight. `hl_group` element can + be omitted for no highlight. • {history} if true, add to |message-history|. • {opts} Optional parameters. • verbose: Message was printed as a result of 'verbose' @@ -782,7 +797,7 @@ nvim_err_writeln({str}) *nvim_err_writeln()* See also: ~ • nvim_err_write() -nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* +nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* Evaluates statusline string. Attributes: ~ @@ -863,16 +878,19 @@ nvim_get_api_info() *nvim_get_api_info()* Returns a 2-tuple (Array), where item 0 is the current channel id and item 1 is the |api-metadata| map (Dictionary). - Return: ~ - 2-tuple [{channel-id}, {api-metadata}] - Attributes: ~ |api-fast| |RPC| only + Return: ~ + 2-tuple `[{channel-id}, {api-metadata}]` + nvim_get_chan_info({chan}) *nvim_get_chan_info()* Gets information about a channel. + Parameters: ~ + • {chan} channel_id, or 0 for current channel + Return: ~ Dictionary describing a channel, with these keys: • "id" Channel id. @@ -882,12 +900,10 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • "stderr" stderr of this Nvim instance • "socket" TCP/IP socket or named pipe • "job" Job with communication over its stdio. - • "mode" How data received on the channel is interpreted. • "bytes" Send and receive raw bytes. • "terminal" |terminal| instance interprets ASCII sequences. • "rpc" |RPC| communication on the channel is active. - • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like "/dev/pts/1". If the name is unknown, the key will still be present if a pty is used (e.g. for conpty on Windows). @@ -919,7 +935,7 @@ nvim_get_color_map() *nvim_get_color_map()* Return: ~ Map of color names and RGB values. -nvim_get_context({*opts}) *nvim_get_context()* +nvim_get_context({opts}) *nvim_get_context()* Gets a map of the current editor state. Parameters: ~ @@ -954,7 +970,7 @@ nvim_get_current_win() *nvim_get_current_win()* Return: ~ Window handle -nvim_get_hl({ns_id}, {*opts}) *nvim_get_hl()* +nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()* Gets all or specific highlight groups in a namespace. Note: ~ @@ -983,7 +999,7 @@ nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* similar to |hlID()|, but allocates a new ID if not present. -nvim_get_hl_ns({*opts}) *nvim_get_hl_ns()* +nvim_get_hl_ns({opts}) *nvim_get_hl_ns()* Gets the active highlight namespace. Parameters: ~ @@ -1032,12 +1048,12 @@ nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for input. - Return: ~ - Dictionary { "mode": String, "blocking": Boolean } - Attributes: ~ |api-fast| + Return: ~ + Dictionary { "mode": String, "blocking": Boolean } + nvim_get_proc({pid}) *nvim_get_proc()* Gets info describing process `pid`. @@ -1099,7 +1115,7 @@ nvim_input({keys}) *nvim_input()* • |keycodes| like <CR> are translated, so "<" is special. To input a literal "<", send <LT>. • For mouse events use |nvim_input_mouse()|. The pseudokey form - "<LeftMouse><col,row>" is deprecated since |api-level| 6. + `<LeftMouse><col,row>` is deprecated since |api-level| 6. Attributes: ~ |api-fast| @@ -1122,7 +1138,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) • Currently this doesn't support "scripting" multiple mouse events by calling it multiple times in a loop: the intermediate mouse positions will be ignored. It should be used to implement real-time mouse input - in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of + in a GUI. The deprecated pseudokey form (`<LeftMouse><col,row>`) of |nvim_input()| has the same limitation. Attributes: ~ @@ -1130,7 +1146,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) Parameters: ~ • {button} Mouse button: one of "left", "right", "middle", "wheel", - "move". + "move", "x1", "x2". • {action} For ordinary buttons, one of "press", "drag", "release". For the wheel, one of "up", "down", "left", "right". Ignored for "move". @@ -1230,7 +1246,9 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* be to the pty master end. For instance, a carriage return is sent as a "\r", not as a "\n". |textlock| applies. It is possible to call |nvim_chan_send()| directly in the - callback however. ["input", term, bufnr, data] + callback however. `["input", term, bufnr, data]` + • force_crlf: (boolean, default true) Convert "\n" to + "\r\n". Return: ~ Channel id, or 0 on error @@ -1260,13 +1278,13 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* • {data} Multiline input. May be binary (containing NUL bytes). • {crlf} Also break lines at CR and CRLF. • {phase} -1: paste in a single call (i.e. without streaming). To - "stream" a paste, call `nvim_paste` sequentially with these `phase` values: + "stream" a paste, call `nvim_paste` sequentially with these + `phase` values: • 1: starts the paste (exactly once) • 2: continues the paste (zero or more times) • 3: ends the paste (exactly once) Return: ~ - • true: Client may continue pasting. • false: Client must cancel the paste. @@ -1429,20 +1447,20 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ • {window} Window handle -nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* +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: + • 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'. - • 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. - • If `link` is used in combination with other attributes; only the `link` - will take effect (see |:hi-link|). + • 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. + • If `link` is used in combination with other attributes; only the + `link` will take effect (see |:hi-link|). Parameters: ~ • {ns_id} Namespace id for this highlight |nvim_create_namespace()|. @@ -1452,9 +1470,9 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* activate them. • {name} Highlight group name, e.g. "ErrorMsg" • {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" + • fg: color name or "#RRGGBB", see note. + • bg: color name or "#RRGGBB", see note. + • sp: color name or "#RRGGBB" • blend: integer between 0 and 100 • bold: boolean • standout: boolean @@ -1499,13 +1517,13 @@ nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()* Parameters: ~ • {ns_id} the namespace to activate -nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* +nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. To set a buffer-local mapping, use |nvim_buf_set_keymap()|. Unlike |:map|, leading/trailing whitespace is accepted as part of the - {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. + {lhs} or {rhs}. Empty {rhs} is <Nop>. |keycodes| are replaced as usual. Example: >vim call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) @@ -1516,14 +1534,14 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* < Parameters: ~ - • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or - "!" for |:map!|, or empty string for |:map|. "ia", "ca" or + • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) + or "!" for |:map!|, or empty string for |:map|. "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline mode, or both, respectively • {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 - except |<buffer>|, values are booleans (default false). Also: + except <buffer>, values are booleans (default false). Also: • "noremap" disables |recursive_mapping|, like |:noremap| • "desc" human-readable description. • "callback" Lua function called in place of {rhs}. @@ -1630,7 +1648,7 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object -nvim_exec2({src}, {*opts}) *nvim_exec2()* +nvim_exec2({src}, {opts}) *nvim_exec2()* Executes Vimscript (multiline block of Ex commands), like anonymous |:source|. @@ -1671,8 +1689,8 @@ nvim_parse_expression({expr}, {flags}, {highlight}) operator/space, though also yielding an error). • "l" when needing to start parsing with lvalues for ":let" or ":for". Common flag sets: - • "m" to parse like for ":echo". - • "E" to parse like for "<C-r>=". + • "m" to parse like for `":echo"`. + • "E" to parse like for `"<C-r>="`. • empty string for ":call". • "lm" to parse for ":let". • {highlight} If true, return value will also include "highlight" key @@ -1683,22 +1701,20 @@ nvim_parse_expression({expr}, {flags}, {highlight}) region [start_col, end_col)). Return: ~ - • AST: top-level dictionary with these keys: • "error": Dictionary with error, present only if parser saw some error. Contains the following keys: • "message": String, error message in printf format, translated. Must contain exactly one "%.*s". • "arg": String, error message argument. - • "len": Amount of bytes successfully parsed. With flags equal to "" - that should be equal to the length of expr string. (“Successfully - parsed” here means “participated in AST creation”, not “till the - first error”.) + that should be equal to the length of expr string. ("Successfully + parsed" here means "participated in AST creation", not "till the + first error".) • "ast": AST, either nil or a dictionary with these keys: • "type": node type, one of the value names from ExprASTNodeType stringified without "kExprNode" prefix. - • "start": a pair [line, column] describing where node is + • "start": a pair `[line, column]` describing where node is "started" where "line" is always 0 (will not be 0 if you will be using this API on e.g. ":let", but that is not present yet). Both elements are Integers. @@ -1709,7 +1725,6 @@ nvim_parse_expression({expr}, {flags}, {highlight}) is zero, one or two children, key will not be present if node has no children. Maximum number of children may be found in node_maxchildren array. - • Local values (present only for certain nodes): • "scope": a single Integer, specifies scope for "Option" and "PlainIdentifier" nodes. For "Option" it is one of ExprOptScope @@ -1739,11 +1754,11 @@ nvim_parse_expression({expr}, {flags}, {highlight}) Command Functions *api-command* *nvim_buf_create_user_command()* -nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts}) +nvim_buf_create_user_command({buffer}, {name}, {command}, {opts}) Creates a buffer-local command |user-commands|. Parameters: ~ - • {buffer} Buffer handle, or 0 for current buffer. + • {buffer} Buffer handle, or 0 for current buffer. See also: ~ • nvim_create_user_command @@ -1759,7 +1774,7 @@ nvim_buf_del_user_command({buffer}, {name}) • {buffer} Buffer handle, or 0 for current buffer. • {name} Name of the command to delete. -nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* +nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* Gets a map of buffer-local |user-commands|. Parameters: ~ @@ -1769,7 +1784,7 @@ nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* Return: ~ Map of maps describing commands. -nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* +nvim_cmd({cmd}, {opts}) *nvim_cmd()* Executes an Ex command. Unlike |nvim_command()| this command takes a structured Dictionary instead @@ -1804,7 +1819,7 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* • |nvim_command()| *nvim_create_user_command()* -nvim_create_user_command({name}, {command}, {*opts}) +nvim_create_user_command({name}, {command}, {opts}) Creates a global |user-commands| command. For Lua usage see |lua-guide-commands-create|. @@ -1824,22 +1839,21 @@ nvim_create_user_command({name}, {command}, {*opts}) argument that contains the following keys: • name: (string) Command name • args: (string) The args passed to the command, if any - |<args>| + <args> • fargs: (table) The args split by unescaped whitespace - (when more than one argument is allowed), if any - |<f-args>| + (when more than one argument is allowed), if any <f-args> • nargs: (string) Number of arguments |:command-nargs| • bang: (boolean) "true" if the command was executed with a - ! modifier |<bang>| + ! modifier <bang> • line1: (number) The starting line of the command range - |<line1>| + <line1> • line2: (number) The final line of the command range - |<line2>| + <line2> • range: (number) The number of items in the command range: - 0, 1, or 2 |<range>| - • count: (number) Any count supplied |<count>| - • reg: (string) The optional register, if specified |<reg>| - • mods: (string) Command modifiers, if any |<mods>| + 0, 1, or 2 <range> + • count: (number) Any count supplied <count> + • reg: (string) The optional register, if specified <reg> + • mods: (string) Command modifiers, if any <mods> • smods: (table) Command modifiers in a structured format. Has the same structure as the "mods" key of |nvim_parse_cmd()|. @@ -1864,7 +1878,7 @@ nvim_del_user_command({name}) *nvim_del_user_command()* Parameters: ~ • {name} Name of the command to delete. -nvim_get_commands({*opts}) *nvim_get_commands()* +nvim_get_commands({opts}) *nvim_get_commands()* Gets a map of global (non-buffer-local) Ex commands. Currently only |user-commands| are supported, not builtin Ex commands. @@ -1893,16 +1907,15 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* Return: ~ Dictionary containing command information, with these keys: • cmd: (string) Command name. - • range: (array) (optional) Command range (|<line1>| |<line2>|). - Omitted if command doesn't accept a range. Otherwise, has no - elements if no range was specified, one element if only a single - range item was specified, or two elements if both range items were - specified. - • count: (number) (optional) Command |<count>|. Omitted if command + • range: (array) (optional) Command range (<line1> <line2>). Omitted + if command doesn't accept a range. Otherwise, has no elements if no + range was specified, one element if only a single range item was + specified, or two elements if both range items were specified. + • count: (number) (optional) Command <count>. Omitted if command cannot take a count. - • reg: (string) (optional) Command |<register>|. Omitted if command + • reg: (string) (optional) Command <register>. Omitted if command cannot take a register. - • bang: (boolean) Whether command contains a |<bang>| (!) modifier. + • bang: (boolean) Whether command contains a <bang> (!) modifier. • args: (array) Command arguments. • addr: (string) Value of |:command-addr|. Uses short name or "line" for -addr=lines. @@ -1916,13 +1929,11 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* • bar: (boolean) The "|" character is treated as a command separator and the double quote character (") is treated as the start of a comment. - • mods: (dictionary) |:command-modifiers|. • filter: (dictionary) |:filter|. • pattern: (string) Filter pattern. Empty string if there is no filter. • force: (boolean) Whether filter is inverted or not. - • silent: (boolean) |:silent|. • emsg_silent: (boolean) |:silent!|. • unsilent: (boolean) |:unsilent|. @@ -1965,7 +1976,7 @@ nvim_get_all_options_info() *nvim_get_all_options_info()* See also: ~ • |nvim_get_commands()| -nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* +nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()* Gets the option information for one option from arbitrary buffer or window Resulting dictionary has keys: @@ -1999,7 +2010,7 @@ nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* Return: ~ Option Information -nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* +nvim_get_option_value({name}, {opts}) *nvim_get_option_value()* Gets the value of an option. The behavior of this function matches that of |:set|: the local value of an option is returned if it exists; otherwise, the global value is returned. Local values always correspond to the @@ -2022,7 +2033,7 @@ nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* Option value *nvim_set_option_value()* -nvim_set_option_value({name}, {value}, {*opts}) +nvim_set_option_value({name}, {value}, {opts}) Sets the value of an option. The behavior of this function matches that of |:set|: for global-local options, both the global and local value are set unless otherwise specified with {scope}. @@ -2048,15 +2059,15 @@ For more information on buffers, see |buffers|. Unloaded Buffers: ~ Buffers may be unloaded by the |:bunload| command or the buffer's -|'bufhidden'| option. When a buffer is unloaded its file contents are -freed from memory and vim cannot operate on the buffer lines until it is -reloaded (usually by opening the buffer again in a new window). API -methods such as |nvim_buf_get_lines()| and |nvim_buf_line_count()| will be -affected. +|'bufhidden'| option. When a buffer is unloaded its file contents are freed +from memory and vim cannot operate on the buffer lines until it is reloaded +(usually by opening the buffer again in a new window). API methods such as +|nvim_buf_get_lines()| and |nvim_buf_line_count()| will be affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. + nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. @@ -2078,7 +2089,8 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* will be `nvim_buf_changedtick_event`. Not for Lua callbacks. • {opts} Optional parameters. - • on_lines: Lua callback invoked on change. Return `true` to detach. Args: + • on_lines: Lua callback invoked on change. Return a + truthy value (not `false` or `nil`) to detach. Args: • the string "lines" • buffer handle • b:changedtick @@ -2088,10 +2100,10 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • byte count of previous contents • deleted_codepoints (if `utf_sizes` is true) • deleted_codeunits (if `utf_sizes` is true) - • on_bytes: Lua callback invoked on change. This callback receives more granular information about the - change compared to on_lines. Return `true` to detach. Args: + change compared to on_lines. Return a truthy value + (not `false` or `nil`) to detach. Args: • the string "bytes" • buffer handle • b:changedtick @@ -2099,28 +2111,28 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • start column of the changed text • byte offset of the changed text (from the start of the buffer) - • old end row of the changed text - • old end column of the changed text + • old end row of the changed text (offset from start + row) + • old end column of the changed text (if old end row + = 0, offset from start column) • old end byte length of the changed text - • new end row of the changed text - • new end column of the changed text + • new end row of the changed text (offset from start + row) + • new end column of the changed text (if new end row + = 0, offset from start column) • new end byte length of the changed text - • on_changedtick: Lua callback invoked on changedtick increment without text change. Args: • the string "changedtick" • buffer handle • b:changedtick - • on_detach: Lua callback invoked on detach. Args: • the string "detach" • buffer handle - • on_reload: Lua callback invoked on reload. The entire buffer content should be considered changed. Args: • the string "reload" • buffer handle - • utf_sizes: include UTF-32 and UTF-16 size of the replaced region, as args to `on_lines`. • preview: also attach to command preview (i.e. @@ -2156,8 +2168,7 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* only) Return: ~ - Return value of function. NB: will deepcopy Lua values currently, use - upvalues to send Lua references in and out. + Return value of function. nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* Unmaps a buffer-local |mapping| for the given mode. @@ -2235,8 +2246,8 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Gets a list of buffer-local |mapping| definitions. Parameters: ~ - • {mode} Mode short-name ("n", "i", "v", ...) • {buffer} Buffer handle, or 0 for current buffer + • {mode} Mode short-name ("n", "i", "v", ...) Return: ~ Array of |maparg()|-like dictionaries describing mappings. The @@ -2375,7 +2386,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_keymap()* -nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts}) +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) Sets a buffer-local |mapping| for the given mode. Parameters: ~ @@ -2454,9 +2465,9 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, Indexing is zero-based. Row indices are end-inclusive, and column indices are end-exclusive. - 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 = {}`. + 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()| if you are only adding or deleting entire lines. @@ -2569,9 +2580,9 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) 0-indexed (row, col) tuple or empty list () if extmark id was absent *nvim_buf_get_extmarks()* -nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) - Gets |extmarks| (including |signs|) in "traversal order" from a |charwise| - region defined by buffer positions (inclusive, 0-indexed |api-indexing|). +nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) + Gets |extmarks| in "traversal order" from a |charwise| region defined by + buffer positions (inclusive, 0-indexed |api-indexing|). Region can be given as (row,col) tuples, or valid extmark ids (whose positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) @@ -2587,6 +2598,10 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) the `overlap` option might be useful. Otherwise only the start position of an extmark will be considered. + Note: legacy signs placed through the |:sign| commands are implemented as + extmarks and will show up here. Their details array will contain a + `sign_name` field. + Example: >lua local api = vim.api local pos = api.nvim_win_get_cursor(0) @@ -2622,10 +2637,10 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) "virt_text" and "virt_lines" Return: ~ - List of [extmark_id, row, col] tuples in "traversal order". + List of `[extmark_id, row, col]` tuples in "traversal order". *nvim_buf_set_extmark()* -nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) +nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Creates or updates an |extmark|. By default a new extmark is created when no id is passed in, but it is @@ -2657,7 +2672,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) EOL of a line, continue the highlight for the rest of the screen line (just like for diff and cursorline highlight). • virt_text : virtual text to link to this mark. A list of - [text, highlight] tuples, each representing a text chunk + `[text, highlight]` tuples, each representing a text chunk with specified highlight. `highlight` element can either be a single highlight group, or an array of multiple highlight groups that will be stacked (highest priority @@ -2671,7 +2686,6 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) • "right_align": display right aligned in the window. • "inline": display at the specified column, and shift the buffer text to the right as needed. - • virt_text_win_col : position the virtual text at a fixed window column (starting from the first text column of the screen line) instead of "virt_text_pos". @@ -2679,6 +2693,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) text is selected or hidden because of scrolling with 'nowrap' or 'smoothscroll'. Currently only affects "overlay" virt_text. + • virt_text_repeat_linebreak : repeat the virtual text on + wrapped lines. • hl_mode : control how highlights are combined with the highlights of the text. Currently only affects virt_text highlights, but might affect `hl_group` in later versions. @@ -2687,16 +2703,16 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) • "combine": combine with background text color. • "blend": blend with background text color. Not supported for "inline" virt_text. - • virt_lines : virtual lines to add next to this mark This should be an array over lines, where each line in turn is - an array over [text, highlight] tuples. In general, buffer - and window options do not affect the display of the text. - In particular 'wrap' and 'linebreak' options do not take - effect, so the number of extra screen lines will always - match the size of the array. However the 'tabstop' buffer - option is still used for hard tabs. By default lines are - placed below the buffer line containing the mark. + an array over `[text, highlight]` tuples. In general, + buffer and window options do not affect the display of the + text. In particular 'wrap' and 'linebreak' options do not + take effect, so the number of extra screen lines will + always match the size of the array. However the 'tabstop' + buffer option is still used for hard tabs. By default + lines are placed below the buffer line containing the + mark. • virt_lines_above: place virtual lines above instead. • virt_lines_leftcol: Place extmarks in the leftmost column of the window, bypassing sign and number columns. @@ -2715,30 +2731,28 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) text around the mark was deleted and then restored by undo. Defaults to true. • invalidate : boolean that indicates whether to hide the - extmark if the entirety of its range is deleted. If + extmark if the entirety of its range is deleted. For + hidden marks, an "invalid" key is added to the "details" + array of |nvim_buf_get_extmarks()| and family. If "undo_restore" is false, the extmark is deleted instead. - • priority: a priority value for the highlight group or sign - attribute. For example treesitter highlighting uses a - value of 100. + • priority: a priority value for the highlight group, sign + attribute or virtual text. For virtual text, item with + highest priority is drawn last. For example treesitter + highlighting uses a value of 100. • strict: boolean that indicates extmark should not be placed if the line or column value is past the end of the buffer or end of the line respectively. Defaults to true. • sign_text: string of length 1-2 used to display in the - sign column. Note: ranges are unsupported and decorations - are only applied to start_row + sign column. • sign_hl_group: name of the highlight group used to - highlight the sign column text. Note: ranges are - unsupported and decorations are only applied to start_row + highlight the sign column text. • number_hl_group: name of the highlight group used to - highlight the number column. Note: ranges are unsupported - and decorations are only applied to start_row + highlight the number column. • line_hl_group: name of the highlight group used to - highlight the whole line. Note: ranges are unsupported and - decorations are only applied to start_row + highlight the whole line. • cursorline_hl_group: name of the highlight group used to - highlight the line when the cursor is on the same line as - the mark and 'cursorline' is enabled. Note: ranges are - unsupported and decorations are only applied to start_row + highlight the sign column text when the cursor is on the + same line as the mark and 'cursorline' is enabled. • conceal: string which should be either empty or a single character. Enable concealing similar to |:syn-conceal|. When a character is supplied it is used as |:syn-cchar|. @@ -2750,6 +2764,11 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) drawn by a UI. When set, the UI will receive win_extmark events. Note: the mark is positioned by virt_text attributes. Can be used together with virt_text. + • url: A URL to associate with this extmark. In the TUI, the + OSC 8 control sequence is used to generate a clickable + hyperlink to this URL. + • scoped: boolean that indicates that the extmark should + only be displayed in the namespace scope. (experimental) Return: ~ Id of the created/updated extmark @@ -2777,7 +2796,7 @@ nvim_get_namespaces() *nvim_get_namespaces()* dict that maps from names to namespace ids. *nvim_set_decoration_provider()* -nvim_set_decoration_provider({ns_id}, {*opts}) +nvim_set_decoration_provider({ns_id}, {opts}) Set or change decoration provider for a |namespace| This is a very general purpose interface for having Lua callbacks being @@ -2813,18 +2832,52 @@ nvim_set_decoration_provider({ns_id}, {*opts}) Parameters: ~ • {ns_id} Namespace id from |nvim_create_namespace()| • {opts} Table of callbacks: - • on_start: called first on each screen redraw ["start", - tick] + • on_start: called first on each screen redraw > + ["start", tick] +< • on_buf: called for each buffer being redrawn (before window - callbacks) ["buf", bufnr, tick] - • on_win: called when starting to redraw a specific window. - botline_guess is an approximation that does not exceed the - last line number. ["win", winid, bufnr, topline, - botline_guess] + callbacks) > + ["buf", bufnr, tick] +< + • on_win: called when starting to redraw a specific window. > + ["win", winid, bufnr, topline, botline] +< • on_line: called for each buffer line being redrawn. (The - interaction with fold lines is subject to change) ["win", - winid, bufnr, row] - • on_end: called at the end of a redraw cycle ["end", tick] + interaction with fold lines is subject to change) > + ["line", winid, bufnr, row] +< + • on_end: called at the end of a redraw cycle > + ["end", tick] +< + +nvim_win_add_ns({window}, {ns_id}) *nvim_win_add_ns()* + Adds the namespace scope to the window. + + Parameters: ~ + • {window} Window handle, or 0 for current window + • {ns_id} the namespace to add + + Return: ~ + true if the namespace was added, else false + +nvim_win_get_ns({window}) *nvim_win_get_ns()* + Gets all the namespaces scopes associated with a window. + + Parameters: ~ + • {window} Window handle, or 0 for current window + + Return: ~ + a list of namespaces ids + +nvim_win_remove_ns({window}, {ns_id}) *nvim_win_remove_ns()* + Removes the namespace scope from the window. + + Parameters: ~ + • {window} Window handle, or 0 for current window + • {ns_id} the namespace to remove + + Return: ~ + true if the namespace was removed, else false ============================================================================== @@ -2842,8 +2895,7 @@ nvim_win_call({window}, {fun}) *nvim_win_call()* only) Return: ~ - Return value of function. NB: will deepcopy Lua values currently, use - upvalues to send Lua references in and out. + Return value of function. See also: ~ • |win_execute()| @@ -3002,7 +3054,7 @@ nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()* This takes precedence over the 'winhighlight' option. Parameters: ~ - • {ns_id} the namespace to use + • {ns_id} the namespace to use nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* Sets a window-scoped (w:) variable @@ -3020,7 +3072,7 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()* • {window} Window handle, or 0 for current window • {width} Width as a count of columns -nvim_win_text_height({window}, {*opts}) *nvim_win_text_height()* +nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* Computes the number of screen lines occupied by a range of text in a given window. Works for off-screen text and takes folds into account. @@ -3056,21 +3108,31 @@ nvim_win_text_height({window}, {*opts}) *nvim_win_text_height()* ============================================================================== -Win_Config Functions *api-win_config* +Win_config Functions *api-win_config* -nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* - Open a new window. +nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* + Opens a new split window, or a floating window if `relative` is specified, + or an external window (managed by the UI) if `external` is specified. - Currently this is used to open floating and external windows. Floats are - windows that are drawn above the split layout, at some anchor position in - some other window. Floats can be drawn internally or by external GUI with - the |ui-multigrid| extension. External windows are only supported with - multigrid GUIs, and are displayed as separate top-level windows. + Floats are windows that are drawn above the split layout, at some anchor + position in some other window. Floats can be drawn internally or by + external GUI with the |ui-multigrid| extension. External windows are only + supported with multigrid GUIs, and are displayed as separate top-level + windows. For a general overview of floats, see |api-floatwin|. - Exactly one of `external` and `relative` must be specified. The `width` - and `height` of the new window must be specified. + The `width` and `height` of the new window must be specified when opening + a floating window, but are optional for normal windows. + + If `relative` and `external` are omitted, a normal "split" window is + created. The `win` property determines which window will be split. If no + `win` is provided or `win == 0`, a window will be created adjacent to the + current window. If -1 is provided, a top-level split will be created. + `vertical` and `split` are only valid for normal windows, and are used to + control split direction. For `vertical`, the exact direction is determined + by |'splitright'| and |'splitbelow'|. Split windows cannot have + `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. With relative=editor (row=0,col=0) refers to the top-left corner of the screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right @@ -3091,6 +3153,12 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua vim.api.nvim_open_win(0, false, {relative='win', width=12, height=3, bufpos={100,10}}) +< + + Example (Lua): vertical split left of the current window >lua + vim.api.nvim_open_win(0, false, { + split = 'left', + win = 0 }) < @@ -3108,25 +3176,23 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* window. • "cursor" Cursor position in current window. • "mouse" Mouse position - - • win: |window-ID| for relative="win". + • win: |window-ID| window to split, or relative window when + creating a float (relative="win"). • anchor: Decides which corner of the float to place at (row,col): • "NW" northwest (default) • "NE" northeast • "SW" southwest • "SE" southeast - • width: Window width (in character cells). Minimum of 1. • height: Window height (in character cells). Minimum of 1. • bufpos: Places float relative to buffer text (only when - relative="win"). Takes a tuple of zero-indexed [line, - column]. `row` and `col` if given are applied relative to this position, else they - default to: + relative="win"). Takes a tuple of zero-indexed + `[line, column]`. `row` and `col` if given are applied + relative to this position, else they default to: • `row=1` and `col=0` if `anchor` is "NW" or "NE" • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus like a tooltip near the buffer text). - • row: Row position in units of "screen cell height", may be fractional. • col: Column position in units of "screen cell width", may @@ -3137,8 +3203,9 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* • external: GUI should display the window as an external top-level window. Currently accepts no other positioning configuration together with this. - • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must be larger - than zero. The following screen elements have hard-coded + • zindex: Stacking order. floats with higher `zindex` go on + top on floats with lower indices. Must be larger than + zero. The following screen elements have hard-coded z-indices: • 100: insert completion popupmenu • 200: message scrollback @@ -3146,7 +3213,6 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* wildoptions+=pum) The default value for floats are 50. In general, values below 100 are recommended, unless there is a good reason to overshadow builtin elements. - • style: (optional) Configure the appearance of the window. Currently only supports one value: • "minimal" Nvim will display the window with many UI @@ -3159,14 +3225,13 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* empty. The end-of-buffer region is hidden by setting `eob` flag of 'fillchars' to a space char, and clearing the |hl-EndOfBuffer| region in 'winhighlight'. - • border: Style of (optional) window border. This can either be a string or an array. The string values are • "none": No border (default). • "single": A single line box. • "double": A double line box. - • "rounded": Like "single", but with rounded corners ("╭" - etc.). + • "rounded": Like "single", but with rounded corners + ("╭" etc.). • "solid": Adds padding by a single whitespace cell. • "shadow": A drop shadow effect by blending with the background. @@ -3174,19 +3239,26 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* any divisor of eight. The array will specify the eight chars building up the border in a clockwise fashion starting with the top-left corner. As an example, the - double box style could be specified as [ "╔", "═" ,"╗", - "║", "╝", "═", "╚", "║" ]. If the number of chars are - less than eight, they will be repeated. Thus an ASCII - border could be specified as [ "/", "-", "\\", "|" ], or - all chars the same as [ "x" ]. An empty string can be - used to turn off a specific border, for instance, [ "", - "", "", ">", "", "", "", "<" ] will only make vertical - borders but not horizontal ones. By default, - `FloatBorder` highlight is used, which links to - `WinSeparator` when not defined. It could also be - specified by character: [ ["+", "MyCorner"], ["x", - "MyBorder"] ]. - + double box style could be specified as: > + [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. +< + If the number of chars are less than eight, they will be + repeated. Thus an ASCII border could be specified as > + [ "/", "-", \"\\\\\", "|" ], +< + or all chars the same as > + [ "x" ]. +< + An empty string can be used to turn off a specific border, + for instance, > + [ "", "", "", ">", "", "", "", "<" ] +< + will only make vertical borders but not horizontal ones. + By default, `FloatBorder` highlight is used, which links + to `WinSeparator` when not defined. It could also be + specified by character: > + [ ["+", "MyCorner"], ["x", "MyBorder"] ]. +< • title: Title (optional) in window border, string or list. List should consist of `[text, highlight]` tuples. If string, the default highlight group is `FloatTitle`. @@ -3205,6 +3277,8 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* • fixed: If true when anchor is NW or SW, the float window would be kept fixed even if the window would be truncated. • hide: If true the floating window will be hidden. + • vertical: Split vertically |:vertical|. + • split: Split direction: "left", "right", "above", "below". Return: ~ Window handle, or 0 on error @@ -3222,7 +3296,7 @@ nvim_win_get_config({window}) *nvim_win_get_config()* Return: ~ Map defining the window configuration, see |nvim_open_win()| -nvim_win_set_config({window}, {*config}) *nvim_win_set_config()* +nvim_win_set_config({window}, {config}) *nvim_win_set_config()* Configures window layout. Currently only for floating and external windows (including changing a split window to those layouts). @@ -3302,11 +3376,18 @@ nvim_tabpage_set_var({tabpage}, {name}, {value}) • {name} Variable name • {value} Variable value +nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()* + Sets the current window in a tabpage + + Parameters: ~ + • {tabpage} Tabpage handle, or 0 for current tabpage + • {win} Window handle, must already belong to {tabpage} + ============================================================================== Autocmd Functions *api-autocmd* -nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* +nvim_clear_autocmds({opts}) *nvim_clear_autocmds()* Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|. @@ -3316,24 +3397,21 @@ nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* • event: "pat1" • event: { "pat1" } • event: { "pat1", "pat2", "pat3" } - • pattern: (string|table) • pattern or patterns to match exactly. • For example, if you have `*.py` as that pattern for the autocmd, you must pass `*.py` exactly to clear it. `test.py` will not match the pattern. - • defaults to clearing all patterns. • NOTE: Cannot be used with {buffer} - • buffer: (bufnr) • clear only |autocmd-buflocal| autocommands. • NOTE: Cannot be used with {pattern} - • group: (string|int) The augroup name or id. - • NOTE: If not passed, will only delete autocmds not in any group. + • NOTE: If not passed, will only delete autocmds not in any + group. -nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* +nvim_create_augroup({name}, {opts}) *nvim_create_augroup()* Create or get an autocommand group |autocmd-groups|. To get an existing group id, do: >lua @@ -3354,8 +3432,10 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* See also: ~ • |autocmd-groups| -nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* - Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). +nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* + Creates an |autocommand| event handler, defined by `callback` (Lua + function or Vimscript function name string) or `command` (Ex command + string). Example using Lua callback: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { @@ -3393,19 +3473,18 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* troubleshooting). • callback (function|string) optional: Lua function (or Vimscript function name, if string) called when the - event(s) is triggered. Lua callback can return true to - delete the autocommand, and receives a table argument with - these keys: + event(s) is triggered. Lua callback can return a truthy + value (not `false` or `nil`) to delete the autocommand. + Receives a table argument with these keys: • id: (number) autocommand id • event: (string) name of the triggered event |autocmd-events| • group: (number|nil) autocommand group id, if any - • match: (string) expanded value of |<amatch>| - • buf: (number) expanded value of |<abuf>| - • file: (string) expanded value of |<afile>| + • match: (string) expanded value of <amatch> + • buf: (number) expanded value of <abuf> + • file: (string) expanded value of <afile> • data: (any) arbitrary data passed from |nvim_exec_autocmds()| - • command (string) optional: Vim command to execute on event. Cannot be used with {callback} • once (boolean) optional: defaults to false. Run the @@ -3455,7 +3534,7 @@ nvim_del_autocmd({id}) *nvim_del_autocmd()* Parameters: ~ • {id} Integer Autocommand id returned by |nvim_create_autocmd()| -nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* +nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* Execute all autocommands for {event} that match the corresponding {opts} |autocmd-execute|. @@ -3469,14 +3548,14 @@ nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* • buffer (integer) optional: buffer number |autocmd-buflocal|. Cannot be used with {pattern}. • modeline (bool) optional: defaults to true. Process the - modeline after the autocommands |<nomodeline>|. + modeline after the autocommands <nomodeline>. • data (any): arbitrary data to send to the autocommand callback. See |nvim_create_autocmd()| for details. See also: ~ • |:doautocmd| -nvim_get_autocmds({*opts}) *nvim_get_autocmds()* +nvim_get_autocmds({opts}) *nvim_get_autocmds()* Get all autocommands that match the corresponding {opts}. These examples will get autocommands matching ALL the given criteria: >lua @@ -3590,13 +3669,12 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* • {height} Popupmenu height, must be greater than zero. nvim_ui_set_focus({gained}) *nvim_ui_set_focus()* - Tells the nvim server if focus was gained or lost by the GUI. + Tells the nvim server if focus was gained or lost by the GUI Attributes: ~ |RPC| only nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* - TODO: Documentation Attributes: ~ |RPC| only @@ -3605,7 +3683,6 @@ nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* Tells Nvim when a terminal event has occurred The following terminal events are supported: - • "termresponse": The terminal sent an OSC or DCS response sequence to Nvim. The payload is the received response. Sets |v:termresponse| and fires |TermResponse|. @@ -3614,11 +3691,10 @@ nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* |RPC| only Parameters: ~ - • {event} Event name - • {payload} Event payload + • {event} Event name + • {value} Event payload nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* - TODO: Documentation Attributes: ~ |RPC| only @@ -3638,4 +3714,5 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) • {width} The new requested width. • {height} The new requested height. + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: |