diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 209 |
1 files changed, 136 insertions, 73 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ea3a8242ae..0c726ddd86 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -70,7 +70,7 @@ Nvim instance: nvim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS']) result = nvim.call(:nvim_command, 'echo "hello world!"') < -A better way is to use the Python REPL with the `neovim` package, where API +A better way is to use the Python REPL with the "pynvim" package, where API functions can be called interactively: > >>> from pynvim import attach @@ -336,7 +336,7 @@ 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). -|nvim_buf_attach| will take keyword args for the callbacks. "on_lines" will +|nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline}, {new_lastline}, {old_byte_size}[, {old_utf32_size}, {old_utf16_size}]). Unlike remote channel events the text contents are not passed. The new text can @@ -355,7 +355,7 @@ was changed. The parameters recieved are ("changedtick", {buf}, {changedtick}). *api-lua-detach* In-process Lua callbacks can detach by returning `true`. This will detach all -callbacks attached with the same |nvim_buf_attach| call. +callbacks attached with the same |nvim_buf_attach()| call. ============================================================================== @@ -529,13 +529,11 @@ nvim__id_float({flt}) *nvim__id_float()* nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* TODO: Documentation - *nvim__put_attr()* -nvim__put_attr({id}, {start_row}, {start_col}, {end_row}, {end_col}) - Set attrs in nvim__buf_set_lua_hl callbacks +nvim__screenshot({path}) *nvim__screenshot()* + TODO: Documentation - TODO(bfredl): This is rather pedestrian. The final interface - should probably be derived from a reformed bufhl/virttext - interface with full support for multi-line ranges etc + Attributes: ~ + {fast} nvim__stats() *nvim__stats()* Gets internal stats. @@ -734,13 +732,14 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* On execution error: does not fail, but updates v:errmsg. - If you need to input sequences like <C-o> use nvim_replace_termcodes - to replace the termcodes and then pass the resulting string to - nvim_feedkeys. You'll also want to enable escape_csi. + If you need to input sequences like <C-o> use + |nvim_replace_termcodes| to replace the termcodes and then + pass the resulting string to nvim_feedkeys. You'll also want + to enable escape_csi. Example: > - :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) - :call nvim_feedkeys(key, 'n', v:true) + :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) + :call nvim_feedkeys(key, 'n', v:true) < Parameters: ~ @@ -1473,6 +1472,53 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ {window} Window handle + *nvim_set_decoration_provider()* +nvim_set_decoration_provider({ns_id}, {opts}) + Set or change decoration provider for a namespace + + This is a very general purpose interface for having lua + callbacks being triggered during the redraw code. + + The expected usage is to set extmarks for the currently + redrawn buffer. |nvim_buf_set_extmark| can be called to add + marks on a per-window or per-lines basis. Use the `ephemeral` + key to only use the mark for the current screen redraw (the + callback will be called again for the next redraw ). + + Note: this function should not be called often. Rather, the + callbacks themselves can be used to throttle unneeded + callbacks. the `on_start` callback can return `false` to + disable the provider until the next redraw. Similarily, return + `false` in `on_win` will skip the `on_lines` calls for that + window (but any extmarks set in `on_win` will still be used). + A plugin managing multiple sources of decorations should + ideally only set one provider, and merge the sources + internally. You can use multiple `ns_id` for the extmarks + set/modified inside the callback anyway. + + Note: doing anything other than setting extmarks is considered + experimental. Doing things like changing options are not + expliticly forbidden, but is likely to have unexpected + consequences (such as 100% CPU consumption). doing + `vim.rpcnotify` should be OK, but `vim.rpcrequest` is quite + dubious for the moment. + + Parameters: ~ + {ns_id} Namespace id from |nvim_create_namespace()| + {opts} Callbacks invoked during redraw: + • on_start: called first on each screen redraw + ["start", tick] + • on_buf: called for each buffer being redrawn + (before window callbacks) ["buf", bufnr, tick] + • on_win: called when starting to redraw a + specific window. ["win", winid, bufnr, topline, + botline_guess] + • on_line: called for each buffer line being + redrawn. (The interation with fold lines is + subject to change) ["win", winid, bufnr, row] + • on_end: called at the end of a redraw cycle + ["end", tick] + nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. @@ -1564,28 +1610,10 @@ affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. - *nvim__buf_add_decoration()* -nvim__buf_add_decoration({buffer}, {ns_id}, {hl_group}, {start_row}, - {start_col}, {end_row}, {end_col}, - {virt_text}) - TODO: Documentation - *nvim__buf_redraw_range()* nvim__buf_redraw_range({buffer}, {first}, {last}) TODO: Documentation -nvim__buf_set_luahl({buffer}, {opts}) *nvim__buf_set_luahl()* - Unstabilized interface for defining syntax hl in lua. - - This is not yet safe for general use, lua callbacks will need - to be restricted, like textlock and probably other stuff. - - The API on_line/nvim__put_attr is quite raw and not intended - to be the final shape. Ideally this should operate on chunks - larger than a single line to reduce interpreter overhead, and - generate annotation objects (bufhl/virttext) on the fly but - using the same representation. - nvim__buf_stats({buffer}) *nvim__buf_stats()* TODO: Documentation @@ -1602,19 +1630,20 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, 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` . + 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. + |nvim_create_namespace()| to create a new empty namespace. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -1688,6 +1717,29 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* |nvim_buf_detach()| |api-buffer-updates-lua| +nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* + call a function with buffer as temporary current buffer + + This temporarily switches current buffer to "buffer". If the + current window already shows "buffer", the window is not + switched If a window inside the current tabpage (including a + float) already shows the buffer One of these windows will be + set as current window temporarily. Otherwise a temporary + scratch window (calleed the "autocmd window" for historical + reasons) will be used. + + This is useful e.g. to call vimL functions that only work with + the current buffer/window currently, like |termopen()|. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {fun} Function to call inside the buffer (currently + lua callable only) + + Return: ~ + Return value of function. NB: will deepcopy lua values + currently, use upvalues to send lua references in and out. + *nvim_buf_clear_namespace()* nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) Clears namespaced objects (highlights, extmarks, virtual text) @@ -1731,6 +1783,17 @@ nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* {buffer} Buffer handle, or 0 for current buffer {name} Variable name +nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()* + Deletes the buffer. See |:bwipeout| + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {opts} Optional parameters. Keys: + • force: Force deletion and ignore unsaved + changes. + • unload: Unloaded only, do not delete. See + |:bunload| + nvim_buf_detach({buffer}) *nvim_buf_detach()* Deactivates buffer-update events on the channel. @@ -1765,13 +1828,16 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* Map of maps describing commands. *nvim_buf_get_extmark_by_id()* -nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}) +nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) 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 + {opts} Optional parameters. Keys: + • limit: Maximum number of marks to return + • details Whether to include the details dict Return: ~ (row, col) tuple or empty list () if extmark id was absent @@ -1820,6 +1886,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) extmark id (whose position defines the bound) {opts} Optional parameters. Keys: • limit: Maximum number of marks to return + • details Whether to include the details dict Return: ~ List of [extmark_id, row, col] tuples in "traversal @@ -1918,28 +1985,6 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* Return: ~ Variable value - *nvim_buf_get_virtual_text()* -nvim_buf_get_virtual_text({buffer}, {line}) - 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(). - - 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 - {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 more info about unloaded buffers. @@ -1973,22 +2018,40 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_extmark()* -nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) +nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Creates or updates an extmark. To create a new extmark, pass id=0. The extmark id will be - returned. It is also allowed to create a new mark by passing - in a previously unused id, but the caller must then keep track - of existing and unused ids itself. (Useful over RPC, to avoid + returned. To move an existing mark, pass its id. + + It is also allowed to create a new mark by passing in a + previously unused id, but the caller must then keep track of + existing and unused ids itself. (Useful over RPC, to avoid waiting for the return value.) + Using the optional arguments, it is possible to use this to + highlight a range of text, and also to associate virtual text + to the mark. + Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| - {id} Extmark id, or 0 to create new {line} Line number where to place the mark {col} Column where to place the mark - {opts} Optional parameters. Currently not used. + {opts} Optional parameters. + • id : id of the extmark to edit. + • end_line : ending line of the mark, 0-based + inclusive. + • end_col : ending col of the mark, 0-based + inclusive. + • hl_group : name of the highlight group used to + highlight this mark. + • virt_text : virtual text to link to this mark. + • ephemeral : for use with + |nvim_set_decoration_provider| callbacks. The + mark will only be used for the current redraw + cycle, and not be permantently stored in the + buffer. Return: ~ Id of the created/updated extmark @@ -2065,12 +2128,12 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks}, Namespaces are used to support batch deletion/updating of virtual text. To create a namespace, use - |nvim_create_namespace|. Virtual text is cleared using - |nvim_buf_clear_namespace|. The same `ns_id` can be used for + |nvim_create_namespace()|. Virtual text is cleared using + |nvim_buf_clear_namespace()|. The same `ns_id` can be used for both virtual text and highlights added by - |nvim_buf_add_highlight|, both can then be cleared with a - single call to |nvim_buf_clear_namespace|. If the virtual text - never will be cleared by an API call, pass `ns_id = -1` . + |nvim_buf_add_highlight()|, both can then be cleared with a + single call to |nvim_buf_clear_namespace()|. If the virtual + text never will be cleared by an API call, pass `ns_id = -1` . As a shorthand, `ns_id = 0` can be used to create a new namespace for the virtual text, the allocated id is then |