diff options
Diffstat (limited to 'runtime/doc')
100 files changed, 12817 insertions, 10494 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 95a929b808..ba3b7c0915 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -7,7 +7,7 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes -via |RPC|, |Lua| and VimL (|eval-api|). +via |RPC|, |Lua| and Vimscript (|eval-api|). Applications can also embed libnvim to work with the C API directly. @@ -17,8 +17,15 @@ Applications can also embed libnvim to work with the C API directly. API Usage *api-rpc* *RPC* *rpc* *msgpack-rpc* -RPC is the typical way to control Nvim programmatically. Nvim implements the -MessagePack-RPC protocol: +RPC is the main way to control Nvim programmatically. Nvim implements the +MessagePack-RPC protocol with these extra (out-of-spec) constraints: + +1. Responses must be given in reverse order of requests (like "unwinding + a stack"). +2. Nvim processes all messages (requests and notifications) in the order they + are received. + +MessagePack-RPC specification: https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md @@ -202,7 +209,7 @@ any of these approaches: nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)' < 3. Use the |api_info()| Vimscript function. >vim - :lua print(vim.inspect(vim.fn.api_info())) + :lua vim.print(vim.fn.api_info()) < Example using |filter()| to exclude non-deprecated API functions: >vim :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') @@ -273,7 +280,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, changed but not the buffer contents. {linedata} contains the changed screen lines. This happens when 'inccommand' shows a buffer preview. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) {changedtick} value of |b:changedtick| for the buffer. If you send an @@ -306,7 +313,7 @@ nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick_event* When |b:changedtick| was incremented but no text was changed. Relevant for undo/redo. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) {changedtick} new value of |b:changedtick| for the buffer @@ -319,7 +326,7 @@ nvim_buf_detach_event[{buf}] *nvim_buf_detach_event* |:checktime| or 'autoread'. - Generally: whenever the buffer contents are unloaded from memory. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) @@ -356,6 +363,7 @@ In-process Lua plugins can receive buffer updates in the form of Lua callbacks. These callbacks are called frequently in various contexts; |textlock| prevents changing buffer contents and window layout (use |vim.schedule()| to defer such operations to the main loop instead). +Moving the cursor is allowed, but it is restored afterwards. |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline}, @@ -399,6 +407,23 @@ external highlighter plugin wants to add many highlights in a batch, performance can be improved by calling |nvim_buf_add_highlight()| as an asynchronous notification, after first (synchronously) requesting a source id. +|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to +be tracked or manipulated after adding them, it is better to use +|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark| +id. Thus, instead of >lua + vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end) +< +use >lua + -- create the highlight through an extmark + extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group}) + + -- example: modify the extmark's highlight group + vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) + + -- example: change the highlight's position + vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) +< + Example using the Python API client (|pynvim|): >python src = vim.new_highlight_source() @@ -451,6 +476,11 @@ Buffer text can be highlighted by typical mechanisms (syntax highlighting, options from the current window; specify `style=minimal` in |nvim_open_win()| to disable various visual features such as the 'number' column. +Other highlight groups specific to floating windows: +- |hl-FloatBorder| for window's border +- |hl-FloatTitle| for window's title +- |hl-FloatFooter| for window's footer + Currently, floating windows don't support some widgets like scrollbar. The output of |:mksession| does not include commands for restoring floating @@ -464,7 +494,7 @@ Example: create a float with scratch buffer: >vim \ 'row': 1, 'anchor': 'NW', 'style': 'minimal'} let win = nvim_open_win(buf, 0, opts) " optional: change highlight, otherwise Pmenu is used - call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') + call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win}) < ============================================================================== @@ -558,7 +588,7 @@ nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* Parameters: ~ • {pat} pattern of files to search for • {all} whether to return all matches or only the first - • {opts} is_lua: only search lua subdirs + • {opts} is_lua: only search Lua subdirs Return: ~ list of absolute paths to the found files @@ -615,6 +645,10 @@ nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* NB: if your UI doesn't use hlstate, this will not return hlstate first time. +nvim__invalidate_glyph_cache() *nvim__invalidate_glyph_cache()* + For testing. The condition in schar_cache_clear_if_full is hard to reach, + so this function can be used to force a cache clear in a test. + nvim__stats() *nvim__stats()* Gets internal stats. @@ -679,7 +713,7 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Buffer handle, or 0 on error See also: ~ - buf_open_scratch + • buf_open_scratch nvim_del_current_line() *nvim_del_current_line()* Deletes the current line. @@ -693,13 +727,13 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. See also: ~ - |nvim_set_keymap()| + • |nvim_set_keymap()| nvim_del_mark({name}) *nvim_del_mark()* Deletes an uppercase/file named mark. See |mark-motions|. - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -708,8 +742,8 @@ nvim_del_mark({name}) *nvim_del_mark()* true if the mark was deleted, else false. See also: ~ - |nvim_buf_del_mark()| - |nvim_get_mark()| + • |nvim_buf_del_mark()| + • |nvim_get_mark()| nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. @@ -746,7 +780,7 @@ nvim_err_writeln({str}) *nvim_err_writeln()* • {str} Message See also: ~ - nvim_err_write() + • nvim_err_write() nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* Evaluates statusline string. @@ -768,6 +802,8 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* • use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid} is ignored. Mutually exclusive with {use_winbar}. + • use_statuscol_lnum: (number) Evaluate statuscolumn for this + line number instead of statusline. Return: ~ Dictionary containing statusline information, with these keys: @@ -820,8 +856,8 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()* true otherwise. See also: ~ - feedkeys() - vim_strsave_escape_ks + • feedkeys() + • vim_strsave_escape_ks nvim_get_api_info() *nvim_get_api_info()* Returns a 2-tuple (Array), where item 0 is the current channel id and item @@ -918,37 +954,48 @@ nvim_get_current_win() *nvim_get_current_win()* Return: ~ Window handle -nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* - Gets a highlight definition by id. |hlID()| - - Parameters: ~ - • {hl_id} Highlight id as returned by |hlID()| - • {rgb} Export RGB colors - - Return: ~ - Highlight definition map - - See also: ~ - nvim_get_hl_by_name +nvim_get_hl({ns_id}, {*opts}) *nvim_get_hl()* + Gets all or specific highlight groups in a namespace. -nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* - Gets a highlight definition by name. + Note: ~ + • When the `link` attribute is defined in the highlight definition map, + other attributes will not be taking effect (see |:hi-link|). Parameters: ~ - • {name} Highlight group name - • {rgb} Export RGB colors + • {ns_id} Get highlight groups for namespace ns_id + |nvim_get_namespaces()|. Use 0 to get global highlight groups + |:highlight|. + • {opts} Options dict: + • name: (string) Get a highlight definition by name. + • id: (integer) Get a highlight definition by id. + • link: (boolean, default true) Show linked group name + instead of effective definition |:hi-link|. + • create: (boolean, default true) When highlight group + doesn't exist create it. Return: ~ - Highlight definition map - - See also: ~ - nvim_get_hl_by_id + Highlight groups as a map from group name to a highlight definition + map as in |nvim_set_hl()|, or only a single highlight definition map + if requested by name or id. 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_hl_ns({*opts}) *nvim_get_hl_ns()* + Gets the active highlight namespace. + + Parameters: ~ + • {opts} Optional parameters + • winid: (number) |window-ID| for retrieving a window's + highlight namespace. A value of -1 is returned when + |nvim_win_set_hl_ns()| has not been called for the window + (or was called with a namespace of -1). + + Return: ~ + Namespace id, or -1 + nvim_get_keymap({mode}) *nvim_get_keymap()* Gets a list of global (non-buffer-local) |mapping| definitions. @@ -960,13 +1007,14 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* "buffer" key is always zero. nvim_get_mark({name}, {opts}) *nvim_get_mark()* - Return a tuple (row, col, buffer, buffername) representing the position of - the uppercase/file named mark. See |mark-motions|. + Returns a `(row, col, buffer, buffername)` tuple representing the position + of the uppercase/file named mark. "End of line" column position is + returned as |v:maxcol| (big number). See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -977,8 +1025,8 @@ nvim_get_mark({name}, {opts}) *nvim_get_mark()* not set. See also: ~ - |nvim_buf_set_mark()| - |nvim_del_mark()| + • |nvim_buf_set_mark()| + • |nvim_del_mark()| nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for @@ -1047,12 +1095,10 @@ nvim_input({keys}) *nvim_input()* On execution error: does not fail, but updates v:errmsg. - Note: - |keycodes| like <CR> are translated, so "<" is special. To input a + 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 + • For mouse events use |nvim_input_mouse()|. The pseudokey form "<LeftMouse><col,row>" is deprecated since |api-level| 6. Attributes: ~ @@ -1072,8 +1118,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) 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 + Note: ~ + • Currently this doesn't support "scripting" multiple mouse events b |