diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 2065 |
1 files changed, 1176 insertions, 889 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 98dd330b48..ea3a8242ae 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -19,6 +19,7 @@ API Usage *api-rpc* *RPC* *rpc* *msgpack-rpc* RPC is the typical way to control Nvim programmatically. Nvim implements the MessagePack-RPC protocol: + https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md Many clients use the API: user interfaces (GUIs), remote plugins, scripts like @@ -182,21 +183,17 @@ External programs (clients) can use the metadata to discover the API, using any of these approaches: 1. Connect to a running Nvim instance and call |nvim_get_api_info()| via - msgpack-rpc. This is best for clients written in dynamic languages which + msgpack-RPC. This is best for clients written in dynamic languages which can define functions at runtime. - 2. Start Nvim with the |--api-info| option. Useful for clients written in - statically-compiled languages. - - 3. Use the |api_info()| Vimscript function. - -Example: To get a human-readable list of API functions: > - :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') -< -Example: To get a formatted dump of the API using python (requires the -"pyyaml" and "msgpack-python" modules): > - nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' + 2. Start Nvim with |--api-info|. Useful for statically-compiled clients. + Example (requires Python "pyyaml" and "msgpack-python" modules): > + nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' < + 3. Use the |api_info()| Vimscript function. > + :lua print(vim.inspect(vim.fn.api_info())) +< Example using |filter()| to exclude non-deprecated API functions: > + :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') ============================================================================== API contract *api-contract* @@ -439,141 +436,170 @@ Example: create a float with scratch buffer: > > ============================================================================== +Extended marks *api-extended-marks* + +Extended marks (extmarks) represent buffer annotations that track text changes +in the buffer. They could be used to represent cursors, folds, misspelled +words, and anything else that needs to track a logical location in the buffer +over time. + +Example: + +We will set an extmark at the first row and third column. |api-indexing| is +zero-indexed, so we use row=0 and column=2. Passing id=0 creates a new mark +and returns the id: > + + let g:mark_ns = nvim_create_namespace('myplugin') + let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 0, 2, {}) + +We can get a mark by its id: > + + echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id) + => [0, 2] + +We can get all marks in a buffer for our namespace (or by a range): > + + echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {}) + => [[1, 0, 2]] + +Deleting all text surrounding an extmark does not remove the extmark. To +remove an extmark use |nvim_buf_del_extmark()|. + +Namespaces allow your plugin to manage only its own extmarks, ignoring those +created by another plugin. + +Extmark positions changed by an edit will be restored on undo/redo. Creating +and deleting extmarks is not a buffer change, thus new undo states are not +created for extmark changes. + +============================================================================== Global Functions *api-global* -nvim_command({command}) *nvim_command()* - Executes an ex-command. +nvim__get_lib_dir() *nvim__get_lib_dir()* + TODO: Documentation - On execution error: fails with VimL error, does not update - v:errmsg. +nvim__id({obj}) *nvim__id()* + Returns object given as argument. + + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {command} Ex-command string + {obj} Object to return. -nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* - Gets a highlight definition by name. + Return: ~ + its argument. + +nvim__id_array({arr}) *nvim__id_array()* + Returns array given as argument. + + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {name} Highlight group name - {rgb} Export RGB colors + {arr} Array to return. Return: ~ - Highlight definition map + its argument. - See also: ~ - nvim_get_hl_by_id +nvim__id_dictionary({dct}) *nvim__id_dictionary()* + Returns dictionary given as argument. -nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* - Gets a highlight definition by id. |hlID()| + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {hl_id} Highlight id as returned by |hlID()| - {rgb} Export RGB colors + {dct} Dictionary to return. Return: ~ - Highlight definition map - - See also: ~ - nvim_get_hl_by_name + its argument. -nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* - Sends input-keys to Nvim, subject to various quirks controlled - by `mode` flags. This is a blocking call, unlike - |nvim_input()|. +nvim__id_float({flt}) *nvim__id_float()* + Returns floating-point value given as argument. - On execution error: does not fail, but updates v:errmsg. + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {keys} to be typed - {mode} behavior flags, see |feedkeys()| - {escape_csi} If true, escape K_SPECIAL/CSI bytes in - `keys` + {flt} Value to return. - See also: ~ - feedkeys() - vim_strsave_escape_csi + Return: ~ + its argument. -nvim_input({keys}) *nvim_input()* - Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a - low-level input buffer and the call is non-blocking (input is - processed asynchronously by the eventloop). +nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* + TODO: Documentation - On execution error: does not fail, but updates v:errmsg. + *nvim__put_attr()* +nvim__put_attr({id}, {start_row}, {start_col}, {end_row}, {end_col}) + Set attrs in nvim__buf_set_lua_hl callbacks - Note: - |keycodes| like <CR> are translated, so "<" is special. To - input a literal "<", send <LT>. - Note: - For mouse events use |nvim_input_mouse()|. The pseudokey - form "<LeftMouse><col,row>" is deprecated since - |api-level| 6. + TODO(bfredl): This is rather pedestrian. The final interface + should probably be derived from a reformed bufhl/virttext + interface with full support for multi-line ranges etc - Attributes: ~ - {fast} +nvim__stats() *nvim__stats()* + Gets internal stats. + + Return: ~ + Map of various internal stats. + +nvim_call_atomic({calls}) *nvim_call_atomic()* + Calls many API methods atomically. + + This has two main usages: + 1. To perform several requests from an async context + atomically, i.e. without interleaving redraws, RPC requests + from other clients, or user interactions (however API + methods may trigger autocommands or event processing which + have such side-effects, e.g. |:sleep| may wake timers). + 2. To minimize RPC overhead (roundtrips) of a sequence of many + requests. Parameters: ~ - {keys} to be typed + {calls} an array of calls, where each call is described + by an array with two elements: the request name, + and an array of arguments. Return: ~ - Number of bytes actually written (can be fewer than - requested if the buffer becomes full). + Array of two elements. The first is an array of return + values. The second is NIL if all calls succeeded. If a + call resulted in an error, it is a three-element array + with the zero-based index of the call which resulted in an + error, the error type and the error message. If an error + occurred, the values from all preceding calls will still + be returned. - *nvim_input_mouse()* -nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) - Send mouse event from GUI. + *nvim_call_dict_function()* +nvim_call_dict_function({dict}, {fn}, {args}) + Calls a VimL |Dictionary-function| with the given arguments. - Non-blocking: does not wait on any result, but queues the - event to be processed soon by the event loop. + On execution error: fails with VimL error, does not update + v:errmsg. - Note: - 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 - |nvim_input()| has the same limitiation. + Parameters: ~ + {dict} Dictionary, or String evaluating to a VimL |self| + dict + {fn} Name of the function defined on the VimL dict + {args} Function arguments packed in an Array - Attributes: ~ - {fast} + Return: ~ + Result of the function call - Parameters: ~ - {button} Mouse button: one of "left", "right", - "middle", "wheel". - {action} For ordinary buttons, one of "press", "drag", - "release". For the wheel, one of "up", "down", - "left", "right". - {modifier} String of modifiers each represented by a - single char. The same specifiers are used as - for a key press, except that the "-" separator - is optional, so "C-A-", "c-a" and "CA" can all - be used to specify Ctrl+Alt+click. - {grid} Grid number if the client uses |ui-multigrid|, - else 0. - {row} Mouse row-position (zero-based, like redraw - events) - {col} Mouse column-position (zero-based, like redraw - events) +nvim_call_function({fn}, {args}) *nvim_call_function()* + Calls a VimL function with the given arguments. - *nvim_replace_termcodes()* -nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) - Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a - string with the internal representation. + On execution error: fails with VimL error, does not update + v:errmsg. Parameters: ~ - {str} String to be converted. - {from_part} Legacy Vim parameter. Usually true. - {do_lt} Also translate <lt>. Ignored if `special` is - false. - {special} Replace |keycodes|, e.g. <CR> becomes a "\n" - char. + {fn} Function to call + {args} Function arguments packed in an Array - See also: ~ - replace_termcodes - cpoptions + Return: ~ + Result of the function call -nvim_command_output({command}) *nvim_command_output()* - Executes an ex-command and returns its (non-error) output. - Shell |:!| output is not captured. +nvim_command({command}) *nvim_command()* + Executes an ex-command. On execution error: fails with VimL error, does not update v:errmsg. @@ -581,9 +607,79 @@ nvim_command_output({command}) *nvim_command_output()* Parameters: ~ {command} Ex-command string + See also: ~ + |nvim_exec()| + +nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* + Creates a new, empty, unnamed buffer. + + Parameters: ~ + {listed} Sets 'buflisted' + {scratch} Creates a "throwaway" |scratch-buffer| for + temporary work (always 'nomodified'). Also sets + 'nomodeline' on the buffer. + + Return: ~ + Buffer handle, or 0 on error + + See also: ~ + buf_open_scratch + +nvim_create_namespace({name}) *nvim_create_namespace()* + Creates a new namespace, or gets an existing one. + + Namespaces are used for buffer highlights and virtual text, + see |nvim_buf_add_highlight()| and + |nvim_buf_set_virtual_text()|. + + Namespaces can be named or anonymous. If `name` matches an + existing namespace, the associated id is returned. If `name` + is an empty string a new, anonymous namespace is created. + + Parameters: ~ + {name} Namespace name or empty string + + Return: ~ + Namespace id + +nvim_del_current_line() *nvim_del_current_line()* + Deletes the current line. + +nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* + Unmaps a global |mapping| for the given mode. + + To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. + + See also: ~ + |nvim_set_keymap()| + +nvim_del_var({name}) *nvim_del_var()* + Removes a global (g:) variable. + + Parameters: ~ + {name} Variable name + +nvim_err_write({str}) *nvim_err_write()* + Writes a message to the Vim error buffer. Does not append + "\n", the message is buffered (won't display) until a linefeed + is written. + + Parameters: ~ + {str} Message + +nvim_err_writeln({str}) *nvim_err_writeln()* + Writes a message to the Vim error buffer. Appends "\n", so the + buffer is flushed (and displayed). + + Parameters: ~ + {str} Message + + See also: ~ + nvim_err_write() + nvim_eval({expr}) *nvim_eval()* - Evaluates a VimL expression (:help expression). Dictionaries - and Lists are recursively expanded. + Evaluates a VimL |expression|. Dictionaries and Lists are + recursively expanded. On execution error: fails with VimL error, does not update v:errmsg. @@ -594,7 +690,30 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object -nvim_execute_lua({code}, {args}) *nvim_execute_lua()* +nvim_exec({src}, {output}) *nvim_exec()* + 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. + + Parameters: ~ + {src} Vimscript code + {output} Capture and return all (non-error, non-shell + |:!|) output + + Return: ~ + Output (non-error, non-shell |:!|) if `output` is true, + else empty string. + + See also: ~ + |execute()| + |nvim_command()| + +nvim_exec_lua({code}, {args}) *nvim_exec_lua()* Execute Lua code. Parameters (if any) are available as `...` inside the chunk. The chunk can return a value. @@ -608,55 +727,124 @@ nvim_execute_lua({code}, {args}) *nvim_execute_lua()* Return: ~ Return value of Lua code if present or NIL. -nvim_call_function({fn}, {args}) *nvim_call_function()* - Calls a VimL function with the given arguments. +nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* + Sends input-keys to Nvim, subject to various quirks controlled + by `mode` flags. This is a blocking call, unlike + |nvim_input()|. - On execution error: fails with VimL error, does not update - v:errmsg. + On execution error: does not fail, but updates v:errmsg. + + If you need to input sequences like <C-o> use nvim_replace_termcodes + to replace the termcodes and then pass the resulting string to + nvim_feedkeys. You'll also want to enable escape_csi. + + Example: > + :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) + :call nvim_feedkeys(key, 'n', v:true) +< Parameters: ~ - {fn} Function to call - {args} Function arguments packed in an Array + {keys} to be typed + {mode} behavior flags, see |feedkeys()| + {escape_csi} If true, escape K_SPECIAL/CSI bytes in + `keys` + + See also: ~ + feedkeys() + vim_strsave_escape_csi + +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: ~ - Result of the function call + 2-tuple [{channel-id}, {api-metadata}] -nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()* - Calls a VimL |Dictionary-function| with the given arguments. + Attributes: ~ + {fast} - On execution error: fails with VimL error, does not update - v:errmsg. +nvim_get_chan_info({chan}) *nvim_get_chan_info()* + Get information about a channel. + + Return: ~ + Dictionary describing a channel, with these keys: + • "stream" the stream underlying the channel + • "stdio" stdin and stdout of this Nvim instance + • "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" a |terminal| instance interprets ASCII + sequences + • "rpc" |RPC| communication on the channel is active + + • "pty" Name of pseudoterminal, if one is used (optional). + On a POSIX system, this will be a device path like + /dev/pts/1. Even if the name is unknown, the key will + still be present to indicate a pty is used. This is + currently the case when using winpty on windows. + • "buffer" buffer with connected |terminal| instance + (optional) + • "client" information about the client on the other end + of the RPC channel, if it has added it using + |nvim_set_client_info()|. (optional) + +nvim_get_color_by_name({name}) *nvim_get_color_by_name()* + Returns the 24-bit RGB value of a |nvim_get_color_map()| color + name or "#rrggbb" hexadecimal string. + + Example: > + :echo nvim_get_color_by_name("Pink") + :echo nvim_get_color_by_name("#cbcbcb") +< Parameters: ~ - {dict} Dictionary, or String evaluating to a VimL |self| - dict - {fn} Name of the function defined on the VimL dict - {args} Function arguments packed in an Array + {name} Color name or "#rrggbb" string Return: ~ - Result of the function call + 24-bit RGB value, or -1 for invalid argument. -nvim_strwidth({text}) *nvim_strwidth()* - Calculates the number of display cells occupied by `text` . - <Tab> counts as one cell. +nvim_get_color_map() *nvim_get_color_map()* + Returns a map of color names and RGB values. - Parameters: ~ - {text} Some text + Keys are color names (e.g. "Aqua") and values are 24-bit RGB + color values (e.g. 65535). Return: ~ - Number of cells + Map of color names and RGB values. -nvim_list_runtime_paths() *nvim_list_runtime_paths()* - Gets the paths contained in 'runtimepath'. +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. + + Parameters: ~ + {opts} Optional parameters. Currently only supports + {"builtin":false} Return: ~ - List of paths + Map of maps describing commands. -nvim_set_current_dir({dir}) *nvim_set_current_dir()* - Changes the global working directory. +nvim_get_context({opts}) *nvim_get_context()* + Gets a map of the current editor state. Parameters: ~ - {dir} Directory path + {opts} Optional parameters. + • types: List of |context-types| ("regs", "jumps", + "bufs", "gvars", …) to gather, or empty for + "all". + + Return: ~ + map of global |context|. + +nvim_get_current_buf() *nvim_get_current_buf()* + Gets the current buffer. + + Return: ~ + Buffer handle nvim_get_current_line() *nvim_get_current_line()* Gets the current line. @@ -664,52 +852,75 @@ nvim_get_current_line() *nvim_get_current_line()* Return: ~ Current line string -nvim_set_current_line({line}) *nvim_set_current_line()* - Sets the current line. +nvim_get_current_tabpage() *nvim_get_current_tabpage()* + Gets the current tabpage. - Parameters: ~ - {line} Line contents + Return: ~ + Tabpage handle -nvim_del_current_line() *nvim_del_current_line()* - Deletes the current line. +nvim_get_current_win() *nvim_get_current_win()* + Gets the current window. -nvim_get_var({name}) *nvim_get_var()* - Gets a global (g:) variable. + Return: ~ + Window handle + +nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* + Gets a highlight definition by id. |hlID()| Parameters: ~ - {name} Variable name + {hl_id} Highlight id as returned by |hlID()| + {rgb} Export RGB colors Return: ~ - Variable value + Highlight definition map -nvim_set_var({name}, {value}) *nvim_set_var()* - Sets a global (g:) variable. + See also: ~ + nvim_get_hl_by_name + +nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* + Gets a highlight definition by name. Parameters: ~ - {name} Variable name - {value} Variable value + {name} Highlight group name + {rgb} Export RGB colors -nvim_del_var({name}) *nvim_del_var()* - Removes a global (g:) variable. + Return: ~ + Highlight definition map - Parameters: ~ - {name} Variable name + See also: ~ + nvim_get_hl_by_id -nvim_get_vvar({name}) *nvim_get_vvar()* - Gets a v: variable. +nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* + Gets a highlight group by name + + similar to |hlID()|, but allocates a new ID if not present. + +nvim_get_keymap({mode}) *nvim_get_keymap()* + Gets a list of global (non-buffer-local) |mapping| + definitions. Parameters: ~ - {name} Variable name + {mode} Mode short-name ("n", "i", "v", ...) Return: ~ - Variable value + Array of maparg()-like dictionaries describing mappings. + The "buffer" key is always zero. -nvim_set_vvar({name}, {value}) *nvim_set_vvar()* - Sets a v: variable, if it is not readonly. +nvim_get_mode() *nvim_get_mode()* + Gets the current mode. |mode()| "blocking" is true if Nvim is + waiting for input. - Parameters: ~ - {name} Variable name - {value} Variable value + Return: ~ + Dictionary { "mode": String, "blocking": Boolean } + + Attributes: ~ + {fast} + +nvim_get_namespaces() *nvim_get_namespaces()* + Gets existing, non-anonymous namespaces. + + Return: ~ + dict that maps from names to namespace ids. nvim_get_option({name}) *nvim_get_option()* Gets an option value string. @@ -720,38 +931,113 @@ nvim_get_option({name}) *nvim_get_option()* Return: ~ Option value (global) -nvim_set_option({name}, {value}) *nvim_set_option()* - Sets an option value. +nvim_get_proc({pid}) *nvim_get_proc()* + Gets info describing process `pid` . + + Return: ~ + Map of process properties, or NIL if process not found. + +nvim_get_proc_children({pid}) *nvim_get_proc_children()* + Gets the immediate children of process `pid` . + + Return: ~ + Array of child process ids, empty if process not found. + +nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* + Find files in runtime directories + + 'name' can contain wildcards. For example + nvim_get_runtime_file("colors/*.vim", true) will return all + color scheme files. + + It is not an error to not find any files. An empty array is + returned then. Parameters: ~ - {name} Option name - {value} New option value + {name} pattern of files to search for + {all} whether to return all matches or only the first -nvim_out_write({str}) *nvim_out_write()* - Writes a message to the Vim output buffer. Does not append - "\n", the message is buffered (won't display) until a linefeed - is written. + Return: ~ + list of absolute paths to the found files + +nvim_get_var({name}) *nvim_get_var()* + Gets a global (g:) variable. Parameters: ~ - {str} Message + {name} Variable name -nvim_err_write({str}) *nvim_err_write()* - Writes a message to the Vim error buffer. Does not append - "\n", the message is buffered (won't display) until a linefeed - is written. + Return: ~ + Variable value + +nvim_get_vvar({name}) *nvim_get_vvar()* + Gets a v: variable. Parameters: ~ - {str} Message + {name} Variable name -nvim_err_writeln({str}) *nvim_err_writeln()* - Writes a message to the Vim error buffer. Appends "\n", so the - buffer is flushed (and displayed). + Return: ~ + Variable value + +nvim_input({keys}) *nvim_input()* + Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a + low-level input buffer and the call is non-blocking (input is + processed asynchronously by the eventloop). + + On execution error: does not fail, but updates v:errmsg. + + Note: + |keycodes| like <CR> are translated, so "<" is special. To + input a literal "<", send <LT>. + Note: + For mouse events use |nvim_input_mouse()|. The pseudokey + form "<LeftMouse><col,row>" is deprecated since + |api-level| 6. + + Attributes: ~ + {fast} Parameters: ~ - {str} Message + {keys} to be typed - See also: ~ - nvim_err_write() + Return: ~ + Number of bytes actually written (can be fewer than + requested if the buffer becomes full). + + *nvim_input_mouse()* +nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) + Send mouse event from GUI. + + Non-blocking: does not wait on any result, but queues the + event to be processed soon by the event loop. + + Note: + 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 + |nvim_input()| has the same limitiation. + + Attributes: ~ + {fast} + + Parameters: ~ + {button} Mouse button: one of "left", "right", + "middle", "wheel". + {action} For ordinary buttons, one of "press", "drag", + "release". For the wheel, one of "up", "down", + "left", "right". + {modifier} String of modifiers each represented by a + single char. The same specifiers are used as + for a key press, except that the "-" separator + is optional, so "C-A-", "c-a" and "CA" can all + be used to specify Ctrl+Alt+click. + {grid} Grid number if the client uses |ui-multigrid|, + else 0. + {row} Mouse row-position (zero-based, like redraw + events) + {col} Mouse column-position (zero-based, like redraw + events) nvim_list_bufs() *nvim_list_bufs()* Gets the current list of buffer handles @@ -762,49 +1048,48 @@ nvim_list_bufs() *nvim_list_bufs()* Return: ~ List of buffer handles -nvim_get_current_buf() *nvim_get_current_buf()* - Gets the current buffer. +nvim_list_chans() *nvim_list_chans()* + Get information about all open channels. Return: ~ - Buffer handle + Array of Dictionaries, each describing a channel with the + format specified at |nvim_get_chan_info()|. -nvim_set_current_buf({buffer}) *nvim_set_current_buf()* - Sets the current buffer. +nvim_list_runtime_paths() *nvim_list_runtime_paths()* + Gets the paths contained in 'runtimepath'. - Parameters: ~ - {buffer} Buffer handle + Return: ~ + List of paths -nvim_list_wins() *nvim_list_wins()* - Gets the current list of window handles. +nvim_list_tabpages() *nvim_list_tabpages()* + Gets the current list of tabpage handles. Return: ~ - List of window handles + List of tabpage handles -nvim_get_current_win() *nvim_get_current_win()* - Gets the current window. +nvim_list_uis() *nvim_list_uis()* + Gets a list of dictionaries representing attached UIs. Return: ~ - Window handle + Array of UI dictionaries, each with these keys: + • "height" Requested height of the UI + • "width" Requested width of the UI + • "rgb" true if the UI uses RGB colors (false implies + |cterm-colors|) + • "ext_..." Requested UI extensions, see |ui-option| + • "chan" Channel id of remote UI (not present for TUI) -nvim_set_current_win({window}) *nvim_set_current_win()* - Sets the current window. +nvim_list_wins() *nvim_list_wins()* + Gets the current list of window handles. - Parameters: ~ - {window} Window handle + Return: ~ + List of window handles -nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* - Creates a new, empty, unnamed buffer. +nvim_load_context({dict}) *nvim_load_context()* + Sets the current editor state from the given |context| map. Parameters: ~ - {listed} Sets 'buflisted' - {scratch} Creates a "throwaway" |scratch-buffer| for - temporary work (always 'nomodified') - - Return: ~ - Buffer handle, or 0 on error - - See also: ~ - buf_open_scratch + {dict} |Context| map. nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* Open a new window. @@ -849,15 +1134,15 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* {buffer} Buffer to display, or 0 for current buffer {enter} Enter the window (make it the current window) {config} Map defining the window configuration. Keys: - • `relative` : Sets the window layout to "floating", placed - at (row,col) coordinates relative to one of: + • `relative`: Sets the window layout to "floating", placed + at (row,col) coordinates relative to: • "editor" The global editor grid • "win" Window given by the `win` field, or - current window by default. + current window. • "cursor" Cursor position in current window. • `win` : |window-ID| for relative="win". - • `anchor` : Decides which corner of the float to place + • `anchor`: Decides which corner of the float to place at (row,col): • "NW" northwest (default) • "NE" northeast @@ -887,7 +1172,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* an external top-level window. Currently accepts no other positioning configuration together with this. - • `style` : Configure the appearance of the window. + • `style`: Configure the appearance of the window. Currently only takes one non-empty value: • "minimal" Nvim will display the window with many UI options disabled. This is useful @@ -896,54 +1181,119 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* 'number', 'relativenumber', 'cursorline', 'cursorcolumn', 'foldcolumn', 'spell' and 'list' options. 'signcolumn' is changed to - `auto` . The end-of-buffer region is hidden - by setting `eob` flag of 'fillchars' to a - space char, and clearing the |EndOfBuffer| - region in 'winhighlight'. + `auto` and 'colorcolumn' is cleared. The + end-of-buffer region is hidden by setting + `eob` flag of 'fillchars' to a space char, + and clearing the |EndOfBuffer| region in + 'winhighlight'. Return: ~ Window handle, or 0 on error -nvim_list_tabpages() *nvim_list_tabpages()* - Gets the current list of tabpage handles. - - Return: ~ - List of tabpage handles - -nvim_get_current_tabpage() *nvim_get_current_tabpage()* - Gets the current tabpage. - - Return: ~ - Tabpage handle - -nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* - Sets the current tabpage. +nvim_out_write({str}) *nvim_out_write()* + Writes a message to the Vim output buffer. Does not append + "\n", the message is buffered (won't display) until a linefeed + is written. Parameters: ~ - {tabpage} Tabpage handle - -nvim_create_namespace({name}) *nvim_create_namespace()* - Creates a new namespace, or gets an existing one. + {str} Message - Namespaces are used for buffer highlights and virtual text, - see |nvim_buf_add_highlight()| and - |nvim_buf_set_virtual_text()|. + *nvim_parse_expression()* +nvim_parse_expression({expr}, {flags}, {highlight}) + Parse a VimL expression. - Namespaces can be named or anonymous. If `name` matches an - existing namespace, the associated id is returned. If `name` - is an empty string a new, anonymous namespace is created. + Attributes: ~ + {fast} Parameters: ~ - {name} Namespace name or empty string + {expr} Expression to parse. Always treated as a + single line. + {flags} Flags: + • "m" if multiple expressions in a row are + allowed (only the first one will be + parsed), + • "E" if EOC tokens are not allowed + (determines whether they will stop parsing + process or be recognized as an + 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>=". + • empty string for ":call". + • "lm" to parse for ":let". + {highlight} If true, return value will also include + "highlight" key containing array of 4-tuples + (arrays) (Integer, Integer, Integer, String), + where first three numbers define the + highlighted region and represent line, + starting column and ending column (latter + exclusive: one should highlight region + [start_col, end_col)). Return: ~ - Namespace id -nvim_get_namespaces() *nvim_get_namespaces()* - Gets existing, non-anonymous namespaces. + • 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. - Return: ~ - dict that maps from names to namespace ids. + • "len": Amount of bytes successfully parsed. With flags + equal to "" that should be equal to the length of expr + string. (“Sucessfully 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 "started" where "line" is always 0 (will not be 0 + if you will be using nvim_parse_viml() on e.g. + ":let", but that is not present yet). Both elements + are Integers. + • "len": “length” of the node. This and "start" are + there for debugging purposes primary (debugging + parser and providing debug information). + • "children": a list of nodes described in top/"ast". + There always 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 values, for "PlainIdentifier" + it is one of ExprVarScope values. + • "ident": identifier (without scope, if any), present + for "Option", "PlainIdentifier", "PlainKey" and + "Environment" nodes. + • "name": Integer, register name (one character) or -1. + Only present for "Register" nodes. + • "cmp_type": String, comparison type, one of the value + names from ExprComparisonType, stringified without + "kExprCmp" prefix. Only present for "Comparison" + nodes. + • "ccs_strategy": String, case comparison strategy, one + of the value names from ExprCaseCompareStrategy, + stringified without "kCCStrategy" prefix. Only present + for "Comparison" nodes. + • "augmentation": String, augmentation type for + "Assignment" nodes. Is either an empty string, "Add", + "Subtract" or "Concat" for "=", "+=", "-=" or ".=" + respectively. + • "invert": Boolean, true if result of comparison needs + to be inverted. Only present for "Comparison" nodes. + • "ivalue": Integer, integer value for "Integer" nodes. + • "fvalue": Float, floating-point value for "Float" + nodes. + • "svalue": String, value for "SingleQuotedString" and + "DoubleQuotedString" nodes. nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* Pastes at cursor, in any mode. @@ -984,146 +1334,49 @@ nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()* {type} Edit behavior: any |getregtype()| result, or: • "b" |blockwise-visual| mode (may include width, e.g. "b3") - • "c" |characterwise| mode + • "c" |charwise| mode • "l" |linewise| mode • "" guess by contents, see |setreg()| {after} Insert after cursor (like |p|), or before (like |P|). {follow} Place cursor at end of inserted text. -nvim_subscribe({event}) *nvim_subscribe()* - Subscribes to event broadcasts. - - Parameters: ~ - {event} Event type string - -nvim_unsubscribe({event}) *nvim_unsubscribe()* - Unsubscribes to event broadcasts. - - Parameters: ~ - {event} Event type string - -nvim_get_color_by_name({name}) *nvim_get_color_by_name()* - Returns the 24-bit RGB value of a |nvim_get_color_map()| color - name or "#rrggbb" hexadecimal string. - - Example: > - :echo nvim_get_color_by_name("Pink") - :echo nvim_get_color_by_name("#cbcbcb") -< - - Parameters: ~ - {name} Color name or "#rrggbb" string - - Return: ~ - 24-bit RGB value, or -1 for invalid argument. - -nvim_get_color_map() *nvim_get_color_map()* - Returns a map of color names and RGB values. - - Keys are color names (e.g. "Aqua") and values are 24-bit RGB - color values (e.g. 65535). - - Return: ~ - Map of color names and RGB values. - -nvim_get_context({opts}) *nvim_get_context()* - Gets a map of the current editor state. - - Parameters: ~ - {opts} Optional parameters. - • types: List of |context-types| ("regs", "jumps", - "bufs", "gvars", …) to gather, or empty for - "all". - - Return: ~ - map of global |context|. - -nvim_load_context({dict}) *nvim_load_context()* - Sets the current editor state from the given |context| map. - - Parameters: ~ - {dict} |Context| map. - -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: ~ - {fast} - -nvim_get_keymap({mode}) *nvim_get_keymap()* - Gets a list of global (non-buffer-local) |mapping| - definitions. - - Parameters: ~ - {mode} Mode short-name ("n", "i", "v", ...) - - Return: ~ - Array of maparg()-like dictionaries describing mappings. - The "buffer" key is always zero. - -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. - - Example: > - call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) -< - - is equivalent to: > - nmap <nowait> <Space><NL> <Nop> -< + *nvim_replace_termcodes()* +nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) + Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a + string with the internal representation. Parameters: ~ - {mode} Mode short-name (map command prefix: "n", "i", - "v", "x", …) or "!" for |:map!|, or empty string - 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|. Values are Booleans. Unknown - key is an error. - -nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* - Unmaps a global |mapping| for the given mode. - - To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. + {str} String to be converted. + {from_part} Legacy Vim parameter. Usually true. + {do_lt} Also translate <lt>. Ignored if `special` is + false. + {special} Replace |keycodes|, e.g. <CR> becomes a "\n" + char. See also: ~ - |nvim_set_keymap()| + replace_termcodes + cpoptions -nvim_get_commands({opts}) *nvim_get_commands()* - Gets a map of global (non-buffer-local) Ex commands. + *nvim_select_popupmenu_item()* +nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) + Selects an item in the completion popupmenu. - Currently only |user-commands| are supported, not builtin Ex - commands. + If |ins-completion| is not active this API call is silently + ignored. Useful for an external UI using |ui-popupmenu| to + control the popupmenu with the mouse. Can also be used in a + mapping; use <cmd> |:map-cmd| to ensure the mapping doesn't + end completion mode. Parameters: ~ - {opts} Optional parameters. Currently only supports - {"builtin":false} - - Return: ~ - Map of maps describing commands. - -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: ~ - {fast} + {item} Index (zero-based) of the item to select. Value + of -1 selects nothing and restores the original + text. + {insert} Whether the selection should be inserted in the + buffer. + {finish} Finish the completion and dismiss the popupmenu. + Implies `insert` . + {opts} Optional parameters. Reserved for future use. *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, @@ -1190,269 +1443,114 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, small logo or icon. .png or .svg format is preferred. -nvim_get_chan_info({chan}) *nvim_get_chan_info()* - Get information about a channel. - - Return: ~ - Dictionary describing a channel, with these keys: - • "stream" the stream underlying the channel - • "stdio" stdin and stdout of this Nvim instance - • "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" a |terminal| instance interprets ASCII - sequences - • "rpc" |RPC| communication on the channel is active - - • "pty" Name of pseudoterminal, if one is used (optional). - On a POSIX system, this will be a device path like - /dev/pts/1. Even if the name is unknown, the key will - still be present to indicate a pty is used. This is - currently the case when using winpty on windows. - • "buffer" buffer with connected |terminal| instance - (optional) - • "client" information about the client on the other end - of the RPC channel, if it has added it using - |nvim_set_client_info()|. (optional) +nvim_set_current_buf({buffer}) *nvim_set_current_buf()* + Sets the current buffer. -nvim_list_chans() *nvim_list_chans()* - Get information about all open channels. + Parameters: ~ + {buffer} Buffer handle - Return: ~ - Array of Dictionaries, each describing a channel with the - format specified at |nvim_get_chan_info()|. +nvim_set_current_dir({dir}) *nvim_set_current_dir()* + Changes the global working directory. -nvim_call_atomic({calls}) *nvim_call_atomic()* - Calls many API methods atomically. + Parameters: ~ + {dir} Directory path - This has two main usages: - 1. To perform several requests from an async context - atomically, i.e. without interleaving redraws, RPC requests - from other clients, or user interactions (however API - methods may trigger autocommands or event processing which - have such side-effects, e.g. |:sleep| may wake timers). - 2. To minimize RPC overhead (roundtrips) of a sequence of many - requests. +nvim_set_current_line({line}) *nvim_set_current_line()* + Sets the current line. Parameters: ~ - {calls} an array of calls, where each call is described - by an array with two elements: the request name, - and an array of arguments. + {line} Line contents - Return: ~ - Array of two elements. The first is an array of return - values. The second is NIL if all calls succeeded. If a - call resulted in an error, it is a three-element array - with the zero-based index of the call which resulted in an - error, the error type and the error message. If an error - occurred, the values from all preceding calls will still - be returned. +nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* + Sets the current tabpage. - *nvim_parse_expression()* -nvim_parse_expression({expr}, {flags}, {highlight}) - Parse a VimL expression. + Parameters: ~ + {tabpage} Tabpage handle - Attributes: ~ - {fast} +nvim_set_current_win({window}) *nvim_set_current_win()* + Sets the current window. Parameters: ~ - {expr} Expression to parse. Always treated as a - single line. - {flags} Flags: - • "m" if multiple expressions in a row are - allowed (only the first one will be - parsed), - • "E" if EOC tokens are not allowed - (determines whether they will stop parsing - process or be recognized as an - 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>=". - • empty string for ":call". - • "lm" to parse for ":let". - {highlight} If true, return value will also include - "highlight" key containing array of 4-tuples - (arrays) (Integer, Integer, Integer, String), - where first three numbers define the - highlighted region and represent line, - starting column and ending column (latter - exclusive: one should highlight region - [start_col, end_col)). - - Return: ~ + {window} Window handle - • 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. +nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* + Sets a global |mapping| for the given mode. - • "len": Amount of bytes successfully parsed. With flags - equal to "" that should be equal to the length of expr - string. (“Sucessfully 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 "started" where "line" is always 0 (will not be 0 - if you will be using nvim_parse_viml() on e.g. - ":let", but that is not present yet). Both elements - are Integers. - • "len": “length” of the node. This and "start" are - there for debugging purposes primary (debugging - parser and providing debug information). - • "children": a list of nodes described in top/"ast". - There always 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. + To set a buffer-local mapping, use |nvim_buf_set_keymap()|. - • 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 values, for "PlainIdentifier" - it is one of ExprVarScope values. - • "ident": identifier (without scope, if any), present - for "Option", "PlainIdentifier", "PlainKey" and - "Environment" nodes. - • "name": Integer, register name (one character) or -1. - Only present for "Register" nodes. - • "cmp_type": String, comparison type, one of the value - names from ExprComparisonType, stringified without - "kExprCmp" prefix. Only present for "Comparison" - nodes. - • "ccs_strategy": String, case comparison strategy, one - of the value names from ExprCaseCompareStrategy, - stringified without "kCCStrategy" prefix. Only present - for "Comparison" nodes. - • "augmentation": String, augmentation type for - "Assignment" nodes. Is either an empty string, "Add", - "Subtract" or "Concat" for "=", "+=", "-=" or ".=" - respectively. - • "invert": Boolean, true if result of comparison needs - to be inverted. Only present for "Comparison" nodes. - • "ivalue": Integer, integer value for "Integer" nodes. - • "fvalue": Float, floating-point value for "Float" - nodes. - • "svalue": String, value for "SingleQuotedString" and - "DoubleQuotedString" nodes. + Unlike |:map|, leading/trailing whitespace is accepted as part + of the {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are + replaced as usual. -nvim__id({obj}) *nvim__id()* - Returns object given as argument. + Example: > + call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) +< - This API function is used for testing. One should not rely on - its presence in plugins. + is equivalent to: > + nmap <nowait> <Space><NL> <Nop> +< Parameters: ~ - {obj} Object to return. - - Return: ~ - its argument. - -nvim__id_array({arr}) *nvim__id_array()* - Returns array given as argument. + {mode} Mode short-name (map command prefix: "n", "i", + "v", "x", …) or "!" for |:map!|, or empty string + 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|. Values are Booleans. Unknown + key is an error. - This API function is used for testing. One should not rely on - its presence in plugins. +nvim_set_option({name}, {value}) *nvim_set_option()* + Sets an option value. Parameters: ~ - {arr} Array to return. - - Return: ~ - its argument. - -nvim__id_dictionary({dct}) *nvim__id_dictionary()* - Returns dictionary given as argument. + {name} Option name + {value} New option value - This API function is used for testing. One should not rely on - its presence in plugins. +nvim_set_var({name}, {value}) *nvim_set_var()* + Sets a global (g:) variable. Parameters: ~ - {dct} Dictionary to return. - - Return: ~ - its argument. - -nvim__id_float({flt}) *nvim__id_float()* - Returns floating-point value given as argument. + {name} Variable name + {value} Variable value - This API function is used for testing. One should not rely on - its presence in plugins. +nvim_set_vvar({name}, {value}) *nvim_set_vvar()* + Sets a v: variable, if it is not readonly. Parameters: ~ - {flt} Value to return. - - Return: ~ - its argument. - -nvim__stats() *nvim__stats()* - Gets internal stats. - - Return: ~ - Map of various internal stats. - -nvim_list_uis() *nvim_list_uis()* - Gets a list of dictionaries representing attached UIs. + {name} Variable name + {value} Variable value - Return: ~ - Array of UI dictionaries, each with these keys: - • "height" Requested height of the UI - • "width" Requested width of the UI - • "rgb" true if the UI uses RGB colors (false implies - |cterm-colors|) - • "ext_..." Requested UI extensions, see |ui-option| - • "chan" Channel id of remote UI (not present for TUI) +nvim_strwidth({text}) *nvim_strwidth()* + Calculates the number of display cells occupied by `text` . + <Tab> counts as one cell. -nvim_get_proc_children({pid}) *nvim_get_proc_children()* - Gets the immediate children of process `pid` . + Parameters: ~ + {text} Some text Return: ~ - Array of child process ids, empty if process not found. - -nvim_get_proc({pid}) *nvim_get_proc()* - Gets info describing process `pid` . + Number of cells - Return: ~ - Map of process properties, or NIL if process not found. +nvim_subscribe({event}) *nvim_subscribe()* + Subscribes to event broadcasts. - *nvim_select_popupmenu_item()* -nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) - Selects an item in the completion popupmenu. + Parameters: ~ + {event} Event type string - If |ins-completion| is not active this API call is silently - ignored. Useful for an external UI using |ui-popupmenu| to - control the popupmenu with the mouse. Can also be used in a - mapping; use <cmd> |:map-cmd| to ensure the mapping doesn't - end completion mode. +nvim_unsubscribe({event}) *nvim_unsubscribe()* + Unsubscribes to event broadcasts. Parameters: ~ - {item} Index (zero-based) of the item to select. Value - of -1 selects nothing and restores the original - text. - {insert} Whether the selection should be inserted in the - buffer. - {finish} Finish the completion and dismiss the popupmenu. - Implies `insert` . - {opts} Optional parameters. Reserved for future use. - -nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* - TODO: Documentation + {event} Event type string ============================================================================== Buffer Functions *api-buffer* + +For more information on buffers, see |buffers|. + Unloaded Buffers:~ Buffers may be unloaded by the |:bunload| command or the @@ -1466,139 +1564,266 @@ affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. -nvim_buf_line_count({buffer}) *nvim_buf_line_count()* - Gets the buffer line count + *nvim__buf_add_decoration()* +nvim__buf_add_decoration({buffer}, {ns_id}, {hl_group}, {start_row}, + {start_col}, {end_row}, {end_col}, + {virt_text}) + TODO: Documentation + + *nvim__buf_redraw_range()* +nvim__buf_redraw_range({buffer}, {first}, {last}) + TODO: Documentation + +nvim__buf_set_luahl({buffer}, {opts}) *nvim__buf_set_luahl()* + Unstabilized interface for defining syntax hl in lua. + + This is not yet safe for general use, lua callbacks will need + to be restricted, like textlock and probably other stuff. + + The API on_line/nvim__put_attr is quite raw and not intended + to be the final shape. Ideally this should operate on chunks + larger than a single line to reduce interpreter overhead, and + generate annotation objects (bufhl/virttext) on the fly but + using the same representation. + +nvim__buf_stats({buffer}) *nvim__buf_stats()* + TODO: Documentation + + *nvim_buf_add_highlight()* +nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, + {col_start}, {col_end}) + Adds a highlight to buffer. + + Useful for plugins that dynamically generate highlights to a + buffer (like a semantic highlighter or linter). The function + adds a single highlight to a buffer. Unlike |matchaddpos()| + highlights follow changes to line numbering (as lines are + inserted/removed above the highlighted line), like signs and + marks do. + + Namespaces are used for batch deletion/updating of a set of + highlights. To create a namespace, use |nvim_create_namespace| + which returns a namespace id. Pass it in to this function as + `ns_id` to add highlights to the namespace. All highlights in + the same namespace can then be cleared with single call to + |nvim_buf_clear_namespace|. If the highlight never will be + deleted by an API call, pass `ns_id = -1` . + + As a shorthand, `ns_id = 0` can be used to create a new + namespace for the highlight, the allocated id is then + returned. If `hl_group` is the empty string no highlight is + added, but a new `ns_id` is still returned. This is supported + for backwards compatibility, new code should use + |nvim_create_namespace| to create a new empty namespace. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + {buffer} Buffer handle, or 0 for current buffer + {ns_id} namespace to use or -1 for ungrouped + highlight + {hl_group} Name of the highlight group to use + {line} Line to highlight (zero-indexed) + {col_start} Start of (byte-indexed) column range to + highlight + {col_end} End of (byte-indexed) column range to + highlight, or -1 to highlight to end of line Return: ~ - Line count, or 0 for unloaded buffer. |api-buffer| + The ns_id that was used nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* - Activates buffer-update events on a channel, or as lua + Activates buffer-update events on a channel, or as Lua callbacks. + Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its + contents): > + events = {} + vim.api.nvim_buf_attach(0, false, { + on_lines=function(...) table.insert(events, {...}) end}) +< + Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {send_buffer} Set to true if the initial notification - should contain the whole buffer. If so, the - first notification will be a - `nvim_buf_lines_event` . Otherwise, the - first notification will be a - `nvim_buf_changedtick_event` . Not used for - lua callbacks. + {send_buffer} True if the initial notification should + contain the whole buffer: first + notification will be `nvim_buf_lines_event` + . Else the first notification will be + `nvim_buf_changedtick_event` . Not for Lua + callbacks. {opts} Optional parameters. - • `on_lines` : lua callback received on - change. - • `on_changedtick` : lua callback received - on changedtick increment without text - change. - • `utf_sizes` : include UTF-32 and UTF-16 - size of the replaced region. See - |api-buffer-updates-lua| for more - information + • on_lines: Lua callback invoked on change. + Return`true`to detach. Args: + • the string "lines" + • buffer handle + • b:changedtick + • first line that changed (zero-indexed) + • last line that was changed + • last line in the updated range + • byte count of previous contents + • deleted_codepoints (if `utf_sizes` is + true) + • deleted_codeunits (if `utf_sizes` is + true) + + • 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 + + • utf_sizes: include UTF-32 and UTF-16 size + of the replaced region, as args to + `on_lines` . + + Return: ~ + False if attach failed (invalid parameter, or buffer isn't + loaded); otherwise True. TODO: LUA_API_NO_EVAL - Return: ~ - False when updates couldn't be enabled because the buffer - isn't loaded or `opts` contained an invalid key; otherwise - True. TODO: LUA_API_NO_EVAL + See also: ~ + |nvim_buf_detach()| + |api-buffer-updates-lua| -nvim_buf_detach({buffer}) *nvim_buf_detach()* - Deactivates buffer-update events on the channel. + *nvim_buf_clear_namespace()* +nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) + Clears namespaced objects (highlights, extmarks, virtual text) + from a region. + + Lines are 0-indexed. |api-indexing| To clear the namespace in + the entire buffer, specify line_start=0 and line_end=-1. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace to clear, or -1 to clear all + namespaces. + {line_start} Start of range of lines to clear + {line_end} End of range of lines to clear (exclusive) + or -1 to clear to end of buffer. - For Lua callbacks see |api-lua-detach|. +nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* + Removes an extmark. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id Return: ~ - False when updates couldn't be disabled because the buffer - isn't loaded; otherwise True. + true if the extmark was found, else false - *nvim_buf_get_lines()* -nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) - Gets a line-range from the buffer. +nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* + Unmaps a buffer-local |mapping| for the given mode. - Indexing is zero-based, end-exclusive. Negative indices are - interpreted as length+1+index: -1 refers to the index past the - end. So to get the last element use start=-2 and end=-1. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Out-of-bounds indices are clamped to the nearest valid value, - unless `strict_indexing` is set. + See also: ~ + |nvim_del_keymap()| + +nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* + Removes a buffer-scoped (b:) variable Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start} First line index - {end} Last line index (exclusive) - {strict_indexing} Whether out-of-bounds should be an - error. + {buffer} Buffer handle, or 0 for current buffer + {name} Variable name - Return: ~ - Array of lines, or empty array for unloaded buffer. +nvim_buf_detach({buffer}) *nvim_buf_detach()* + Deactivates buffer-update events on the channel. - *nvim_buf_set_lines()* -nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, - {replacement}) - Sets (replaces) a line-range in the buffer. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Indexing is zero-based, end-exclusive. Negative indices are - interpreted as length+1+index: -1 refers to the index past the - end. So to change or delete the last element use start=-2 and - end=-1. + Return: ~ + False if detach failed (because the buffer isn't loaded); + otherwise True. - To insert lines at a given index, set `start` and `end` to the - same index. To delete a range of lines, set `replacement` to - an empty array. + See also: ~ + |nvim_buf_attach()| + |api-lua-detach| for detaching Lua callbacks - Out-of-bounds indices are clamped to the nearest valid value, - unless `strict_indexing` is set. +nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* + Gets a changed tick of a buffer Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start} First line index - {end} Last line index (exclusive) - {strict_indexing} Whether out-of-bounds should be an - error. - {replacement} Array of lines to use as replacement - -nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* - Returns the byte offset of a line (0-indexed). |api-indexing| + {buffer} Buffer handle, or 0 for current buffer - Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is - one byte. 'fileformat' and 'fileencoding' are ignored. The - line index just after the last line gives the total byte-count - of the buffer. A final EOL byte is counted if it would be - written, see 'eol'. + Return: ~ + `b:changedtick` value. - Unlike |line2byte()|, throws error for out-of-bounds indexing. - Returns -1 for unloaded buffer. +nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* + Gets a map of buffer-local |user-commands|. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {index} Line index + {opts} Optional parameters. Currently not used. Return: ~ - Integer byte offset, or -1 for unloaded buffer. + Map of maps describing commands. -nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* - Gets a buffer-scoped (b:) variable. + *nvim_buf_get_extmark_by_id()* +nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}) + Returns position for a given extmark id Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {name} Variable name + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id Return: ~ - Variable value + (row, col) tuple or empty list () if extmark id was absent -nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* - Gets a changed tick of a buffer + *nvim_buf_get_extmarks()* +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) respectively, thus the following are + equivalent: +> + nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) + nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {}) +< + + If `end` is less than `start` , traversal works backwards. + (Useful with `limit` , to get the first marks prior to a given + position.) + + Example: +> + local a = vim.api + local pos = a.nvim_win_get_cursor(0) + local ns = a.nvim_create_namespace('my-plugin') + -- Create new extmark at line 1, column 1. + local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, 0, {}) + -- Create new extmark at line 3, column 1. + local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, 0, {}) + -- Get extmarks only from line 3. + local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) + -- Get all marks in this buffer + namespace. + local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {}) + print(vim.inspect(ms)) +< Parameters: ~ {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {start} Start of range, given as (row, col) or valid + extmark id (whose position defines the bound) + {end} End of range, given as (row, col) or valid + extmark id (whose position defines the bound) + {opts} Optional parameters. Keys: + • limit: Maximum number of marks to return Return: ~ - `b:changedtick` value. + List of [extmark_id, row, col] tuples in "traversal + order". nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Gets a list of buffer-local |mapping| definitions. @@ -1611,49 +1836,67 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Array of maparg()-like dictionaries describing mappings. The "buffer" key holds the associated buffer handle. - *nvim_buf_set_keymap()* -nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) - Sets a buffer-local |mapping| for the given mode. + *nvim_buf_get_lines()* +nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) + Gets a line-range from the buffer. + + Indexing is zero-based, end-exclusive. Negative indices are + interpreted as length+1+index: -1 refers to the index past the + end. So to get the last element use start=-2 and end=-1. + + Out-of-bounds indices are clamped to the nearest valid value, + unless `strict_indexing` is set. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + {buffer} Buffer handle, or 0 for current buffer + {start} First line index + {end} Last line index (exclusive) + {strict_indexing} Whether out-of-bounds should be an + error. - See also: ~ - |nvim_set_keymap()| + Return: ~ + Array of lines, or empty array for unloaded buffer. -nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* - Unmaps a buffer-local |mapping| for the given mode. +nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* + Return a tuple (row,col) representing the position of the + named mark. + + Marks are (1,0)-indexed. |api-indexing| Parameters: ~ {buffer} Buffer handle, or 0 for current buffer + {name} Mark name - See also: ~ - |nvim_del_keymap()| + Return: ~ + (row, col) tuple -nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* - Gets a map of buffer-local |user-commands|. +nvim_buf_get_name({buffer}) *nvim_buf_get_name()* + Gets the full file name for the buffer Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {opts} Optional parameters. Currently not used. Return: ~ - Map of maps describing commands. + Buffer name -nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* - Sets a buffer-scoped (b:) variable +nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* + Returns the byte offset of a line (0-indexed). |api-indexing| - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Variable name - {value} Variable value + Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is + one byte. 'fileformat' and 'fileencoding' are ignored. The + line index just after the last line gives the total byte-count + of the buffer. A final EOL byte is counted if it would be + written, see 'eol'. -nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* - Removes a buffer-scoped (b:) variable + Unlike |line2byte()|, throws error for out-of-bounds indexing. + Returns -1 for unloaded buffer. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {name} Variable name + {index} Line index + + Return: ~ + Integer byte offset, or -1 for unloaded buffer. nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* Gets a buffer option value @@ -1665,30 +1908,37 @@ nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* Return: ~ Option value -nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* - Sets a buffer option value. Passing 'nil' as value deletes the - option (only works if there's a global fallback) +nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* + Gets a buffer-scoped (b:) variable. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {name} Option name - {value} Option value + {name} Variable name -nvim_buf_get_name({buffer}) *nvim_buf_get_name()* - Gets the full file name for the buffer + Return: ~ + Variable value - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + *nvim_buf_get_virtual_text()* +nvim_buf_get_virtual_text({buffer}, {line}) + Get the virtual text (annotation) for a buffer line. - Return: ~ - Buffer name + The virtual text is returned as list of lists, whereas the + inner lists have either one or two elements. The first element + is the actual text, the optional second element is the + highlight group. -nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* - Sets the full file name for a buffer + The format is exactly the same as given to + nvim_buf_set_virtual_text(). + + If there is no virtual text associated with the given line, an + empty list is returned. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {name} Buffer name + {line} Line to get the virtual text from (zero-indexed) + + Return: ~ + List of virtual text chunks nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* Checks if a buffer is valid and loaded. See |api-buffer| for @@ -1713,78 +1963,98 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* Return: ~ true if the buffer is valid, false otherwise. -nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* - Return a tuple (row,col) representing the position of the - named mark. +nvim_buf_line_count({buffer}) *nvim_buf_line_count()* + Gets the buffer line count - Marks are (1,0)-indexed. |api-indexing| + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + + Return: ~ + Line count, or 0 for unloaded buffer. |api-buffer| + + *nvim_buf_set_extmark()* +nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) + Creates or updates an extmark. + + To create a new extmark, pass id=0. The extmark id will be + returned. It is also allowed to create a new mark by passing + in a previously unused id, but the caller must then keep track + of existing and unused ids itself. (Useful over RPC, to avoid + waiting for the return value.) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {name} Mark name + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id, or 0 to create new + {line} Line number where to place the mark + {col} Column where to place the mark + {opts} Optional parameters. Currently not used. Return: ~ - (row, col) tuple + Id of the created/updated extmark - *nvim_buf_add_highlight()* -nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, - {col_start}, {col_end}) - Adds a highlight to buffer. + *nvim_buf_set_keymap()* +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) + Sets a buffer-local |mapping| for the given mode. - Useful for plugins that dynamically generate highlights to a - buffer (like a semantic highlighter or linter). The function - adds a single highlight to a buffer. Unlike |matchaddpos()| - highlights follow changes to line numbering (as lines are - inserted/removed above the highlighted line), like signs and - marks do. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - Namespaces are used for batch deletion/updating of a set of - highlights. To create a namespace, use |nvim_create_namespace| - which returns a namespace id. Pass it in to this function as - `ns_id` to add highlights to the namespace. All highlights in - the same namespace can then be cleared with single call to - |nvim_buf_clear_namespace|. If the highlight never will be - deleted by an API call, pass `ns_id = -1` . + See also: ~ + |nvim_set_keymap()| - As a shorthand, `ns_id = 0` can be used to create a new - namespace for the highlight, the allocated id is then - returned. If `hl_group` is the empty string no highlight is - added, but a new `ns_id` is still returned. This is supported - for backwards compatibility, new code should use - |nvim_create_namespace| to create a new empty namespace. + *nvim_buf_set_lines()* +nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, + {replacement}) + Sets (replaces) a line-range in the buffer. + + Indexing is zero-based, end-exclusive. Negative indices are + interpreted as length+1+index: -1 refers to the index past the + end. So to change or delete the last element use start=-2 and + end=-1. + + To insert lines at a given index, set `start` and `end` to the + same index. To delete a range of lines, set `replacement` to + an empty array. + + Out-of-bounds indices are clamped to the nearest valid value, + unless `strict_indexing` is set. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} namespace to use or -1 for ungrouped - highlight - {hl_group} Name of the highlight group to use - {line} Line to highlight (zero-indexed) - {col_start} Start of (byte-indexed) column range to - highlight - {col_end} End of (byte-indexed) column range to - highlight, or -1 to highlight to end of line + {buffer} Buffer handle, or 0 for current buffer + {start} First line index + {end} Last line index (exclusive) + {strict_indexing} Whether out-of-bounds should be an + error. + {replacement} Array of lines to use as replacement - Return: ~ - The ns_id that was used +nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* + Sets the full file name for a buffer - *nvim_buf_clear_namespace()* -nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) - Clears namespaced objects, highlights and virtual text, from a - line range + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Buffer name - Lines are 0-indexed. |api-indexing| To clear the namespace in - the entire buffer, specify line_start=0 and line_end=-1. +nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* + Sets a buffer option value. Passing 'nil' as value deletes the + option (only works if there's a global fallback) Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace to clear, or -1 to clear all - namespaces. - {line_start} Start of range of lines to clear - {line_end} End of range of lines to clear (exclusive) - or -1 to clear to end of buffer. + {buffer} Buffer handle, or 0 for current buffer + {name} Option name + {value} Option value + +nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* + Sets a buffer-scoped (b:) variable + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Variable name + {value} Variable value *nvim_buf_set_virtual_text()* -nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) +nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks}, + {opts}) Set the virtual text (annotation) for a buffer line. By default (and currently the only option) the text will be @@ -1821,105 +2091,77 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) Return: ~ The ns_id that was used -nvim__buf_stats({buffer}) *nvim__buf_stats()* - TODO: Documentation - ============================================================================== Window Functions *api-window* -nvim_win_get_buf({window}) *nvim_win_get_buf()* - Gets the current buffer in a window +nvim_win_close({window}, {force}) *nvim_win_close()* + Closes the window (like |:close| with a |window-ID|). Parameters: ~ {window} Window handle, or 0 for current window + {force} Behave like `:close!` The last window of a + buffer with unwritten changes can be closed. The + buffer will become hidden, even if 'hidden' is + not set. - Return: ~ - Buffer handle - -nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* - Sets the current buffer in a window, without side-effects +nvim_win_del_var({window}, {name}) *nvim_win_del_var()* + Removes a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window - {buffer} Buffer handle + {name} Variable name -nvim_win_get_cursor({window}) *nvim_win_get_cursor()* - Gets the (1,0)-indexed cursor position in the window. - |api-indexing| +nvim_win_get_buf({window}) *nvim_win_get_buf()* + Gets the current buffer in a window Parameters: ~ {window} Window handle, or 0 for current window Return: ~ - (row, col) tuple + Buffer handle -nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* - Sets the (1,0)-indexed cursor position in the window. - |api-indexing| +nvim_win_get_config({window}) *nvim_win_get_config()* + Gets window configuration. - Parameters: ~ - {window} Window handle, or 0 for current window - {pos} (row, col) tuple representing the new position + The returned value may be given to |nvim_open_win()|. -nvim_win_get_height({window}) *nvim_win_get_height()* - Gets the window height + `relative` is empty for normal windows. Parameters: ~ {window} Window handle, or 0 for current window Return: ~ - Height as a count of rows - -nvim_win_set_height({window}, {height}) *nvim_win_set_height()* - Sets the window height. This will only succeed if the screen - is split horizontally. - - Parameters: ~ - {window} Window handle, or 0 for current window - {height} Height as a count of rows + Map defining the window configuration, see + |nvim_open_win()| -nvim_win_get_width({window}) *nvim_win_get_width()* - Gets the window width +nvim_win_get_cursor({window}) *nvim_win_get_cursor()* + Gets the (1,0)-indexed cursor position in the window. + |api-indexing| Parameters: ~ {window} Window handle, or 0 for current window Return: ~ - Width as a count of columns - -nvim_win_set_width({window}, {width}) *nvim_win_set_width()* - Sets the window width. This will only succeed if the screen is - split vertically. - - Parameters: ~ - {window} Window handle, or 0 for current window - {width} Width as a count of columns + (row, col) tuple -nvim_win_get_var({window}, {name}) *nvim_win_get_var()* - Gets a window-scoped (w:) variable +nvim_win_get_height({window}) *nvim_win_get_height()* + Gets the window height Parameters: ~ {window} Window handle, or 0 for current window - {name} Variable name Return: ~ - Variable value + Height as a count of rows -nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* - Sets a window-scoped (w:) variable +nvim_win_get_number({window}) *nvim_win_get_number()* + Gets the window number Parameters: ~ {window} Window handle, or 0 for current window - {name} Variable name - {value} Variable value - -nvim_win_del_var({window}, {name}) *nvim_win_del_var()* - Removes a window-scoped (w:) variable - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Variable name + Return: ~ + Window number nvim_win_get_option({window}, {name}) *nvim_win_get_option()* Gets a window option value @@ -1931,15 +2173,6 @@ nvim_win_get_option({window}, {name}) *nvim_win_get_option()* Return: ~ Option value -nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()* - Sets a window option value. Passing 'nil' as value deletes the - option(only works if there's a global fallback) - - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Option name - {value} Option value - nvim_win_get_position({window}) *nvim_win_get_position()* Gets the window position in display cells. First position is zero. @@ -1959,14 +2192,24 @@ nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()* Return: ~ Tabpage that contains the window -nvim_win_get_number({window}) *nvim_win_get_number()* - Gets the window number +nvim_win_get_var({window}, {name}) *nvim_win_get_var()* + Gets a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window + {name} Variable name Return: ~ - Window number + Variable value + +nvim_win_get_width({window}) *nvim_win_get_width()* + Gets the window width + + Parameters: ~ + {window} Window handle, or 0 for current window + + Return: ~ + Width as a count of columns nvim_win_is_valid({window}) *nvim_win_is_valid()* Checks if a window is valid @@ -1977,6 +2220,13 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()* Return: ~ true if the window is valid, false otherwise +nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* + Sets the current buffer in a window, without side-effects + + Parameters: ~ + {window} Window handle, or 0 for current window + {buffer} Buffer handle + 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 @@ -1994,67 +2244,76 @@ nvim_win_set_config({window}, {config}) *nvim_win_set_config()* See also: ~ |nvim_open_win()| -nvim_win_get_config({window}) *nvim_win_get_config()* - Gets window configuration. +nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* + Sets the (1,0)-indexed cursor position in the window. + |api-indexing| - The returned value may be given to |nvim_open_win()|. + Parameters: ~ + {window} Window handle, or 0 for current window + {pos} (row, col) tuple representing the new position - `relative` is empty for normal windows. +nvim_win_set_height({window}, {height}) *nvim_win_set_height()* + Sets the window height. This will only succeed if the screen + is split horizontally. Parameters: ~ {window} Window handle, or 0 for current window + {height} Height as a count of rows - Return: ~ - Map defining the window configuration, see - |nvim_open_win()| +nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()* + Sets a window option value. Passing 'nil' as value deletes the + option(only works if there's a global fallback) -nvim_win_close({window}, {force}) *nvim_win_close()* - Closes the window (like |:close| with a |window-ID|). + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Option name + {value} Option value + +nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* + Sets a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window - {force} Behave like `:close!` The last window of a - buffer with unwritten changes can be closed. The - buffer will become hidden, even if 'hidden' is - not set. + {name} Variable name + {value} Variable value + +nvim_win_set_width({window}, {width}) *nvim_win_set_width()* + Sets the window width. This will only succeed if the screen is + split vertically. + + Parameters: ~ + {window} Window handle, or 0 for current window + {width} Width as a count of columns ============================================================================== Tabpage Functions *api-tabpage* -nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* - Gets the windows in a tabpage +nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* + Removes a tab-scoped (t:) variable Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name - Return: ~ - List of windows in `tabpage` - -nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* - Gets a tab-scoped (t:) variable +nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* + Gets the tabpage number Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage - {name} Variable name Return: ~ - Variable value + Tabpage number -nvim_tabpage_set_var({tabpage}, {name}, {value}) *nvim_tabpage_set_var()* - Sets a tab-scoped (t:) variable +nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* + Gets a tab-scoped (t:) variable Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage {name} Variable name - {value} Variable value - -nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* - Removes a tab-scoped (t:) variable - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage - {name} Variable name + Return: ~ + Variable value nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* Gets the current window in a tabpage @@ -2065,23 +2324,32 @@ nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* Return: ~ Window handle -nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* - Gets the tabpage number +nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* + Checks if a tabpage is valid Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage Return: ~ - Tabpage number + true if the tabpage is valid, false otherwise -nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* - Checks if a tabpage is valid +nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* + Gets the windows in a tabpage Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage Return: ~ - true if the tabpage is valid, false otherwise + List of windows in `tabpage` + + *nvim_tabpage_set_var()* +nvim_tabpage_set_var({tabpage}, {name}, {value}) + Sets a tab-scoped (t:) variable + + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name + {value} Variable value ============================================================================== @@ -2110,12 +2378,38 @@ nvim_ui_detach() *nvim_ui_detach()* Removes the client from the list of UIs. |nvim_list_uis()| -nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* - TODO: Documentation + *nvim_ui_pum_set_bounds()* +nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) + Tells Nvim the geometry of the popumenu, to align floating + windows with an external popup menu. + + Note that this method is not to be confused with + |nvim_ui_pum_set_height()|, which sets the number of visible + items in the popup menu, while this function sets the bounding + box of the popup menu, including visual decorations such as + boarders and sliders. Floats need not use the same font size, + nor be anchored to exact grid corners, so one can set + floating-point numbers to the popup menu geometry. + + Parameters: ~ + {width} Popupmenu width. + {height} Popupmenu height. + {row} Popupmenu row. + {col} Popupmenu height. + +nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* + Tells Nvim the number of elements displaying in the popumenu, + to decide <PageUp> and <PageDown> movement. + + Parameters: ~ + {height} Popupmenu height, must be greater than zero. nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation +nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* + TODO: Documentation + *nvim_ui_try_resize_grid()* nvim_ui_try_resize_grid({grid}, {width}, {height}) Tell Nvim to resize a grid. Triggers a grid_resize event with @@ -2129,11 +2423,4 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) {width} The new requested width. {height} The new requested height. -nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* - Tells Nvim the number of elements displaying in the popumenu, - to decide <PageUp> and <PageDown> movement. - - Parameters: ~ - {height} Popupmenu height, must be greater than zero. - vim:tw=78:ts=8:ft=help:norl: |