diff options
| author | Justin M. Keyes <justinkz@gmail.com> | 2019-12-28 03:27:25 -0800 |
|---|---|---|
| committer | Justin M. Keyes <justinkz@gmail.com> | 2019-12-30 03:31:32 -0800 |
| commit | c24f8f46b45f097dbe0abf7e6ae686bc9bec5568 (patch) | |
| tree | 028223c62b9d716846b423870a891c62bb0fd8f1 | |
| parent | b81547ce6d182e2a7518e5a2f80d1ee90c5cdb8f (diff) | |
| download | rneovim-c24f8f46b45f097dbe0abf7e6ae686bc9bec5568.tar.gz rneovim-c24f8f46b45f097dbe0abf7e6ae686bc9bec5568.tar.bz2 rneovim-c24f8f46b45f097dbe0abf7e6ae686bc9bec5568.zip | |
gen_vimdoc.py: sort by name
| -rw-r--r-- | runtime/doc/api.txt | 1940 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 146 | ||||
| -rwxr-xr-x | scripts/gen_vimdoc.py | 11 |
3 files changed, 1051 insertions, 1046 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index aa69186cf0..7d45330b66 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -479,166 +479,201 @@ created for extmark changes. ============================================================================== Global Functions *api-global* -nvim_exec({src}, {output}) *nvim_exec()* - Executes Vimscript (multiline block of Ex-commands), like - anonymous |:source|. +nvim__id({obj}) *nvim__id()* + Returns object given as argument. - Unlike |nvim_command()| this function supports heredocs, - script-scope (s:), etc. + This API function is used for testing. One should not rely on + its presence in plugins. - On execution error: fails with VimL error, does not update - v:errmsg. + Parameters: ~ + {obj} Object to return. + + 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: ~ - {src} Vimscript code - {output} Capture and return all (non-error, non-shell - |:!|) output + {arr} Array to return. Return: ~ - Output (non-error, non-shell |:!|) if `output` is true, - else empty string. + its argument. - See also: ~ - |execute()| - |nvim_command()| +nvim__id_dictionary({dct}) *nvim__id_dictionary()* + Returns dictionary given as argument. -nvim_command({command}) *nvim_command()* - Executes an ex-command. + This API function is used for testing. One should not rely on + its presence in plugins. - On execution error: fails with VimL error, does not update - v:errmsg. + Parameters: ~ + {dct} Dictionary to return. + + Return: ~ + its argument. + +nvim__id_float({flt}) *nvim__id_float()* + Returns floating-point value given as argument. + + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {command} Ex-command string + {flt} Value to return. - See also: ~ - |nvim_exec()| + Return: ~ + its argument. -nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* - Gets a highlight definition by name. +nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* + TODO: Documentation + +nvim__put_attr({id}, {c0}, {c1}) *nvim__put_attr()* + Set attrs in nvim__buf_set_lua_hl callbacks + + 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 + +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: ~ - {name} Highlight group name - {rgb} Export RGB colors + {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: ~ - Highlight definition map + 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. - See also: ~ - nvim_get_hl_by_id +nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()* + Calls a VimL |Dictionary-function| with the given arguments. -nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* - Gets a highlight definition by id. |hlID()| + On execution error: fails with VimL error, does not update + v:errmsg. Parameters: ~ - {hl_id} Highlight id as returned by |hlID()| - {rgb} Export RGB colors + {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 Return: ~ - Highlight definition map + Result of the function call - See also: ~ - nvim_get_hl_by_name +nvim_call_function({fn}, {args}) *nvim_call_function()* + Calls a VimL function with the given arguments. -nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* - Gets a highlight group by name + On execution error: fails with VimL error, does not update + v:errmsg. - similar to |hlID()|, but allocates a new ID if not present. + Parameters: ~ + {fn} Function to call + {args} Function arguments packed in an Array -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()|. + Return: ~ + Result of the function call - On execution error: does not fail, but updates v:errmsg. +nvim_command({command}) *nvim_command()* + Executes an ex-command. + + On execution error: fails with VimL error, does not update + v:errmsg. Parameters: ~ - {keys} to be typed - {mode} behavior flags, see |feedkeys()| - {escape_csi} If true, escape K_SPECIAL/CSI bytes in - `keys` + {command} Ex-command string See also: ~ - feedkeys() - vim_strsave_escape_csi + |nvim_exec()| -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_create_buf({listed}, {scratch}) *nvim_create_buf()* + Creates a new, empty, unnamed buffer. - On execution error: does not fail, but updates v:errmsg. + Parameters: ~ + {listed} Sets 'buflisted' + {scratch} Creates a "throwaway" |scratch-buffer| for + temporary work (always 'nomodified') - 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. + Return: ~ + Buffer handle, or 0 on error - Attributes: ~ - {fast} + 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: ~ - {keys} to be typed + {name} Namespace name or empty string Return: ~ - Number of bytes actually written (can be fewer than - requested if the buffer becomes full). + Namespace id - *nvim_input_mouse()* -nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) - Send mouse event from GUI. +nvim_del_current_line() *nvim_del_current_line()* + Deletes the current line. - Non-blocking: does not wait on any result, but queues the - event to be processed soon by the event loop. +nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* + Unmaps a global |mapping| for the given mode. - 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. + To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. - Attributes: ~ - {fast} + See also: ~ + |nvim_set_keymap()| + +nvim_del_var({name}) *nvim_del_var()* + Removes a global (g:) variable. 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) + {name} Variable name - *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. +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} 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. + {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: ~ - replace_termcodes - cpoptions + nvim_err_write() nvim_eval({expr}) *nvim_eval()* Evaluates a VimL |expression|. Dictionaries and Lists are @@ -653,6 +688,29 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object +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. @@ -667,55 +725,115 @@ nvim_exec_lua({code}, {args}) *nvim_exec_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. 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. @@ -723,52 +841,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. @@ -779,38 +920,96 @@ 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` . - Parameters: ~ - {name} Option name - {value} New option value + Return: ~ + Map of process properties, or NIL if process not found. -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. +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_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 @@ -821,49 +1020,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. @@ -916,7 +1114,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* • "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 @@ -946,7 +1144,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 @@ -964,46 +1162,110 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* 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. @@ -1051,139 +1313,42 @@ nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()* |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}, @@ -1250,271 +1415,106 @@ 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. - - 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_get_proc_children({pid}) *nvim_get_proc_children()* - Gets the immediate children of process `pid` . + {name} Variable name + {value} Variable value - Return: ~ - Array of child process ids, empty if process not found. +nvim_strwidth({text}) *nvim_strwidth()* + Calculates the number of display cells occupied by `text` . + <Tab> counts as one cell. -nvim_get_proc({pid}) *nvim_get_proc()* - Gets info describing process `pid` . + Parameters: ~ + {text} Some text Return: ~ - Map of process properties, or NIL if process not found. - - *nvim_select_popupmenu_item()* -nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) - Selects an item in the completion popupmenu. + Number of cells - 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_subscribe({event}) *nvim_subscribe()* + Subscribes 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 -nvim__put_attr({id}, {c0}, {c1}) *nvim__put_attr()* - Set attrs in nvim__buf_set_lua_hl callbacks +nvim_unsubscribe({event}) *nvim_unsubscribe()* + Unsubscribes to event broadcasts. - 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 + Parameters: ~ + {event} Event type string ============================================================================== @@ -1533,14 +1533,65 @@ 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_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}, {ns_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 @@ -1563,7 +1614,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* callbacks. {opts} Optional parameters. • on_lines: Lua callback invoked on change. - Return `true` to detach. Args: + Return`true`to detach. Args: • buffer handle • b:changedtick • first line that changed (zero-indexed) @@ -1597,119 +1648,142 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* |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 + {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. - Return: ~ - False if detach failed (because the buffer isn't loaded); - otherwise True. +nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* + Removes an extmark. - See also: ~ - |nvim_buf_attach()| - |api-lua-detach| for detaching Lua callbacks + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id -nvim__buf_set_luahl({buffer}, {opts}) *nvim__buf_set_luahl()* - Unstabilized interface for defining syntax hl in lua. + Return: ~ + true if the extmark was found, else false - This is not yet safe for general use, lua callbacks will need - to be restricted, like textlock and probably other stuff. +nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* + Unmaps a buffer-local |mapping| for the given mode. - 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. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - *nvim__buf_redraw_range()* -nvim__buf_redraw_range({buffer}, {first}, {last}) - TODO: Documentation + See also: ~ + |nvim_del_keymap()| - *nvim_buf_get_lines()* -nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) - Gets a line-range from the buffer. +nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* + Removes a buffer-scoped (b:) variable - 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 + {name} Variable name - Out-of-bounds indices are clamped to the nearest valid value, - unless `strict_indexing` is set. +nvim_buf_detach({buffer}) *nvim_buf_detach()* + Deactivates buffer-update events on the channel. 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 Return: ~ - Array of lines, or empty array for unloaded buffer. - - *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. + 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. @@ -1722,49 +1796,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 @@ -1776,30 +1868,36 @@ 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({buffer}, {lnum}) *nvim_buf_get_virtual_text()* + 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 @@ -1824,79 +1922,14 @@ 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. - - Marks are (1,0)-indexed. |api-indexing| - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Mark name - - Return: ~ - (row, col) tuple - - *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 - {ns_id} Namespace id from |nvim_create_namespace()| - {id} Extmark id - - Return: ~ - (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 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)) -< +nvim_buf_line_count({buffer}) *nvim_buf_line_count()* + Gets the buffer line count 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: ~ - List of [extmark_id, row, col] tuples in "traversal - order". + Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_extmark()* nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) @@ -1919,73 +1952,64 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) Return: ~ Id of the created/updated extmark -nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* - Removes an extmark. + *nvim_buf_set_keymap()* +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) + Sets a buffer-local |mapping| for the given mode. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace id from |nvim_create_namespace()| - {id} Extmark id - Return: ~ - true if the extmark was found, else false + See also: ~ + |nvim_set_keymap()| - *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_lines()* +nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, + {replacement}) + Sets (replaces) a line-range in the 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. + 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. - 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` . + 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. - 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. + 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, extmarks, virtual text) - from a region. + 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}) @@ -2025,33 +2049,26 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) Return: ~ The ns_id that was used -nvim_buf_get_virtual_text({buffer}, {lnum}) *nvim_buf_get_virtual_text()* - Get the virtual text (annotation) for a buffer line. - 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. - - The format is exactly the same as given to - nvim_buf_set_virtual_text(). +============================================================================== +Window Functions *api-window* - If there is no virtual text associated with the given line, an - empty list is returned. +nvim_win_close({window}, {force}) *nvim_win_close()* + Closes the window (like |:close| with a |window-ID|). Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {line} Line to get the virtual text from (zero-indexed) - - Return: ~ - List of virtual text chunks - -nvim__buf_stats({buffer}) *nvim__buf_stats()* - TODO: Documentation + {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. +nvim_win_del_var({window}, {name}) *nvim_win_del_var()* + Removes a window-scoped (w:) variable -============================================================================== -Window Functions *api-window* + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Variable name nvim_win_get_buf({window}) *nvim_win_get_buf()* Gets the current buffer in a window @@ -2062,12 +2079,19 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()* 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_get_config({window}) *nvim_win_get_config()* + Gets window configuration. + + The returned value may be given to |nvim_open_win()|. + + `relative` is empty for normal windows. Parameters: ~ {window} Window handle, or 0 for current window - {buffer} Buffer handle + + Return: ~ + Map defining the window configuration, see + |nvim_open_win()| nvim_win_get_cursor({window}) *nvim_win_get_cursor()* Gets the (1,0)-indexed cursor position in the window. @@ -2079,14 +2103,6 @@ nvim_win_get_cursor({window}) *nvim_win_get_cursor()* Return: ~ (row, col) tuple -nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* - Sets the (1,0)-indexed cursor position in the window. - |api-indexing| - - Parameters: ~ - {window} Window handle, or 0 for current window - {pos} (row, col) tuple representing the new position - nvim_win_get_height({window}) *nvim_win_get_height()* Gets the window height @@ -2096,55 +2112,14 @@ nvim_win_get_height({window}) *nvim_win_get_height()* 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 - -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_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 - -nvim_win_get_var({window}, {name}) *nvim_win_get_var()* - Gets 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 Return: ~ - Variable 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 - {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 + Window number nvim_win_get_option({window}, {name}) *nvim_win_get_option()* Gets a window option value @@ -2156,15 +2131,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. @@ -2184,14 +2150,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 @@ -2202,6 +2178,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 @@ -2219,67 +2202,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 @@ -2290,23 +2282,31 @@ 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({tabpage}, {name}, {value}) *nvim_tabpage_set_var()* + Sets a tab-scoped (t:) variable + + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name + {value} Variable value ============================================================================== @@ -2335,12 +2335,19 @@ 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_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 @@ -2354,11 +2361,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: diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 1c3a7f70c9..9601537c8d 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -861,6 +861,9 @@ schedule_wrap({cb}) *vim.schedule_wrap()* +deep_equal({a}, {b}) *vim.deep_equal()* + TODO: Documentation + deepcopy({orig}) *vim.deepcopy()* Returns a deep copy of the given object. Non-table objects are copied as in a typical Lua assignment, whereas table objects @@ -889,6 +892,45 @@ gsplit({s}, {sep}, {plain}) *vim.gsplit()* https://www.lua.org/pil/20.2.html http://lua-users.org/wiki/StringLibraryTutorial +is_callable({f}) *vim.is_callable()* + Returns true if object `f` can be called as a function. + + Parameters: ~ + {f} Any object + + Return: ~ + true if `f` is callable, else false + +list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* + Extends a list-like table with the values of another list-like + table. + + NOTE: This mutates dst! + + Parameters: ~ + {dst} list which will be modified and appended to. + {src} list from which values will be inserted. + {start} Start index on src. defaults to 1 + {finish} Final index on src. defaults to #src + + Return: ~ + dst + + See also: ~ + |vim.tbl_extend()| + +pesc({s}) *vim.pesc()* + Escapes magic chars in a Lua pattern string. + + Parameters: ~ + {s} String to escape + + Return: ~ + %-escaped pattern string + + See also: ~ + https://github.com/rxi/lume + split({s}, {sep}, {plain}) *vim.split()* Splits a string at each instance of a separator. @@ -910,28 +952,13 @@ split({s}, {sep}, {plain}) *vim.split()* See also: ~ |vim.gsplit()| -tbl_keys({t}) *vim.tbl_keys()* - Return a list of all keys used in a table. However, the order - of the return table of keys is not guaranteed. - - Parameters: ~ - {t} Table - - Return: ~ - list of keys - - See also: ~ - Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua - -tbl_values({t}) *vim.tbl_values()* - Return a list of all values used in a table. However, the - order of the return table of values is not guaranteed. +tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* + Add the reverse lookup values to an existing table. For + example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = + 1 }` Parameters: ~ - {t} Table - - Return: ~ - list of values + {o} table The table to add the reverse to. tbl_contains({t}, {value}) *vim.tbl_contains()* Checks if a list-like (vector) table contains `value` . @@ -943,10 +970,6 @@ tbl_contains({t}, {value}) *vim.tbl_contains()* Return: ~ true if `t` contains `value` -tbl_isempty({t}) *vim.tbl_isempty()* - See also: ~ - Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua@paramt Table to check - tbl_extend({behavior}, {...}) *vim.tbl_extend()* Merges two or more map-like tables. @@ -961,35 +984,6 @@ tbl_extend({behavior}, {...}) *vim.tbl_extend()* See also: ~ |extend()| -deep_equal({a}, {b}) *vim.deep_equal()* - TODO: Documentation - -tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* - Add the reverse lookup values to an existing table. For - example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = - 1 }` - - Parameters: ~ - {o} table The table to add the reverse to. - -list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* - Extends a list-like table with the values of another list-like - table. - - NOTE: This mutates dst! - - Parameters: ~ - {dst} list which will be modified and appended to. - {src} list from which values will be inserted. - {start} Start index on src. defaults to 1 - {finish} Final index on src. defaults to #src - - Return: ~ - dst - - See also: ~ - |vim.tbl_extend()| - tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are "unrolled" and appended to the result. @@ -1003,6 +997,10 @@ tbl_flatten({t}) *vim.tbl_flatten()* See also: ~ Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua +tbl_isempty({t}) *vim.tbl_isempty()* + See also: ~ + Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua@paramt Table to check + tbl_islist({t}) *vim.tbl_islist()* Table @@ -1010,30 +1008,41 @@ tbl_islist({t}) *vim.tbl_islist()* true: A non-empty array, false: A non-empty table, nil: An empty table -trim({s}) *vim.trim()* - Trim whitespace (Lua pattern "%s") from both sides of a - string. +tbl_keys({t}) *vim.tbl_keys()* + Return a list of all keys used in a table. However, the order + of the return table of keys is not guaranteed. Parameters: ~ - {s} String to trim + {t} Table Return: ~ - String with whitespace removed from its beginning and end + list of keys See also: ~ - https://www.lua.org/pil/20.2.html + Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua -pesc({s}) *vim.pesc()* - Escapes magic chars in a Lua pattern string. +tbl_values({t}) *vim.tbl_values()* + Return a list of all values used in a table. However, the + order of the return table of values is not guaranteed. Parameters: ~ - {s} String to escape + {t} Table Return: ~ - %-escaped pattern string + list of values + +trim({s}) *vim.trim()* + Trim whitespace (Lua pattern "%s") from both sides of a + string. + + Parameters: ~ + {s} String to trim + + Return: ~ + String with whitespace removed from its beginning and end See also: ~ - https://github.com/rxi/lume + https://www.lua.org/pil/20.2.html validate({opt}) *vim.validate()* Validates a parameter specification (types and values). @@ -1085,13 +1094,4 @@ validate({opt}) *vim.validate()* • msg: (optional) error string if validation fails -is_callable({f}) *vim.is_callable()* - Returns true if object `f` can be called as a function. - - Parameters: ~ - {f} Any object - - Return: ~ - true if `f` is callable, else false - vim:tw=78:ts=8:ft=help:norl: diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 891336f571..e30ed92e8f 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -145,7 +145,7 @@ def debug_this(cond, o): except Exception: pass if ((callable(cond) and cond()) - or (not callable(cond) and cond == True) + or (not callable(cond) and cond) or (not callable(cond) and cond in o)): raise RuntimeError('xxx: {}\n{}'.format(name, o)) @@ -312,8 +312,8 @@ def update_params_map(parent, ret_map, width=62): desc = '' desc_node = get_child(node, 'parameterdescription') if desc_node: - desc = fmt_node_as_vimhelp(desc_node, width=width, - indent=(' ' * max_name_len)) + desc = fmt_node_as_vimhelp( + desc_node, width=width, indent=(' ' * max_name_len)) ret_map[name] = desc return ret_map @@ -321,8 +321,10 @@ def update_params_map(parent, ret_map, width=62): def render_node(n, text, prefix='', indent='', width=62): """Renders a node as Vim help text, recursively traversing all descendants.""" global fmt_vimhelp + def ind(s): return s if fmt_vimhelp else '' + text = '' # space_preceding = (len(text) > 0 and ' ' == text[-1][-1]) # text += (int(not space_preceding) * ' ') @@ -666,6 +668,8 @@ def extract_from_xml(filename, mode, width): xrefs.clear() + fns = collections.OrderedDict(sorted(fns.items())) + deprecated_fns = collections.OrderedDict(sorted(deprecated_fns.items())) return (fns, deprecated_fns) @@ -864,6 +868,7 @@ def main(config): with open(doc_file, 'ab') as fp: fp.write(docs.encode('utf8')) + fn_map_full = collections.OrderedDict(sorted(fn_map_full.items())) with open(mpack_file, 'wb') as fp: fp.write(msgpack.packb(fn_map_full, use_bin_type=True)) |