aboutsummaryrefslogtreecommitdiff
path: root/runtime/doc/api.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/api.txt')
-rw-r--r--runtime/doc/api.txt291
1 files changed, 244 insertions, 47 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 98dd330b48..d52a9a8409 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -19,6 +19,7 @@ API Usage *api-rpc* *RPC* *rpc*
*msgpack-rpc*
RPC is the typical way to control Nvim programmatically. Nvim implements the
MessagePack-RPC protocol:
+ https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
Many clients use the API: user interfaces (GUIs), remote plugins, scripts like
@@ -439,8 +440,68 @@ Example: create a float with scratch buffer: >
>
==============================================================================
+Extended marks *api-extended-marks*
+
+Extended marks (extmarks) represent buffer annotations that track text changes
+in the buffer. They could be used to represent cursors, folds, misspelled
+words, and anything else that needs to track a logical location in the buffer
+over time.
+
+Example:
+
+We will set an extmark at the first row and third column. |api-indexing| is
+zero-indexed, so we use row=0 and column=2. Passing id=0 creates a new mark
+and returns the id: >
+
+ let g:mark_ns = nvim_create_namespace('myplugin')
+ let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 0, 2, {})
+
+We can get a mark by its id: >
+
+ echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id)
+ => [0, 2]
+
+We can get all marks in a buffer for our namespace (or by a range): >
+
+ echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {})
+ => [[1, 0, 2]]
+
+Deleting all text surrounding an extmark does not remove the extmark. To
+remove an extmark use |nvim_buf_del_extmark()|.
+
+Namespaces allow your plugin to manage only its own extmarks, ignoring those
+created by another plugin.
+
+Extmark positions changed by an edit will be restored on undo/redo. Creating
+and deleting extmarks is not a buffer change, thus new undo states are not
+created for extmark changes.
+
+==============================================================================
Global Functions *api-global*
+nvim_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_command({command}) *nvim_command()*
Executes an ex-command.
@@ -450,6 +511,9 @@ nvim_command({command}) *nvim_command()*
Parameters: ~
{command} Ex-command string
+ See also: ~
+ |nvim_exec()|
+
nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()*
Gets a highlight definition by name.
@@ -571,19 +635,9 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
replace_termcodes
cpoptions
-nvim_command_output({command}) *nvim_command_output()*
- Executes an ex-command and returns its (non-error) output.
- Shell |:!| output is not captured.
-
- On execution error: fails with VimL error, does not update
- v:errmsg.
-
- Parameters: ~
- {command} Ex-command string
-
nvim_eval({expr}) *nvim_eval()*
- Evaluates a VimL expression (:help expression). Dictionaries
- and Lists are recursively expanded.
+ Evaluates a VimL |expression|. Dictionaries and Lists are
+ recursively expanded.
On execution error: fails with VimL error, does not update
v:errmsg.
@@ -594,7 +648,7 @@ nvim_eval({expr}) *nvim_eval()*
Return: ~
Evaluation result or expanded object
-nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
+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.
@@ -850,10 +904,10 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
{enter} Enter the window (make it the current window)
{config} Map defining the window configuration. Keys:
• `relative` : Sets the window layout to "floating", placed
- at (row,col) coordinates relative to one of:
+ at (row,col) coordinates relative to:
• "editor" The global editor grid
• "win" Window given by the `win` field, or
- current window by default.
+ current window.
• "cursor" Cursor position in current window.
• `win` : |window-ID| for relative="win".
@@ -896,10 +950,11 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
'number', 'relativenumber', 'cursorline',
'cursorcolumn', 'foldcolumn', 'spell' and
'list' options. 'signcolumn' is changed to
- `auto` . The end-of-buffer region is hidden
- by setting `eob` flag of 'fillchars' to a
- space char, and clearing the |EndOfBuffer|
- region in 'winhighlight'.
+ `auto` and 'colorcolumn' is cleared. The
+ end-of-buffer region is hidden by setting
+ `eob` flag of 'fillchars' to a space char,
+ and clearing the |EndOfBuffer| region in
+ 'winhighlight'.
Return: ~
Window handle, or 0 on error
@@ -984,7 +1039,7 @@ nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()*
{type} Edit behavior: any |getregtype()| result, or:
• "b" |blockwise-visual| mode (may include
width, e.g. "b3")
- • "c" |characterwise| mode
+ • "c" |charwise| mode
• "l" |linewise| mode
• "" guess by contents, see |setreg()|
{after} Insert after cursor (like |p|), or before (like
@@ -1476,45 +1531,73 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Line count, or 0 for unloaded buffer. |api-buffer|
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
- Activates buffer-update events on a channel, or as lua
+ Activates buffer-update events on a channel, or as Lua
callbacks.
+ Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its
+ contents): >
+ events = {}
+ vim.api.nvim_buf_attach(0, false, {
+ on_lines=function(...) table.insert(events, {...}) end})
+<
+
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
- {send_buffer} Set to true if the initial notification
- should contain the whole buffer. If so, the
- first notification will be a
- `nvim_buf_lines_event` . Otherwise, the
- first notification will be a
- `nvim_buf_changedtick_event` . Not used for
- lua callbacks.
+ {send_buffer} True if the initial notification should
+ contain the whole buffer: first
+ notification will be `nvim_buf_lines_event`
+ . Else the first notification will be
+ `nvim_buf_changedtick_event` . Not for Lua
+ callbacks.
{opts} Optional parameters.
- • `on_lines` : lua callback received on
- change.
- • `on_changedtick` : lua callback received
- on changedtick increment without text
- change.
- • `utf_sizes` : include UTF-32 and UTF-16
- size of the replaced region. See
- |api-buffer-updates-lua| for more
- information
+ • on_lines: Lua callback invoked on change.
+ Return `true` to detach. Args:
+ • buffer handle
+ • b:changedtick
+ • first line that changed (zero-indexed)
+ • last line that was changed
+ • last line in the updated range
+ • byte count of previous contents
+ • deleted_codepoints (if `utf_sizes` is
+ true)
+ • deleted_codeunits (if `utf_sizes` is
+ true)
+
+ • on_changedtick: Lua callback invoked on
+ changedtick increment without text
+ change. Args:
+ • buffer handle
+ • b:changedtick
+
+ • on_detach: Lua callback invoked on
+ detach. Args:
+ • buffer handle
+
+ • utf_sizes: include UTF-32 and UTF-16 size
+ of the replaced region, as args to
+ `on_lines` .
+
+ Return: ~
+ False if attach failed (invalid parameter, or buffer isn't
+ loaded); otherwise True. TODO: LUA_API_NO_EVAL
- Return: ~
- False when updates couldn't be enabled because the buffer
- isn't loaded or `opts` contained an invalid key; otherwise
- True. TODO: LUA_API_NO_EVAL
+ See also: ~
+ |nvim_buf_detach()|
+ |api-buffer-updates-lua|
nvim_buf_detach({buffer}) *nvim_buf_detach()*
Deactivates buffer-update events on the channel.
- For Lua callbacks see |api-lua-detach|.
-
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
Return: ~
- False when updates couldn't be disabled because the buffer
- isn't loaded; otherwise True.
+ False if detach failed (because the buffer isn't loaded);
+ otherwise True.
+
+ See also: ~
+ |nvim_buf_attach()|
+ |api-lua-detach| for detaching Lua callbacks
*nvim_buf_get_lines()*
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
@@ -1726,6 +1809,99 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
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))
+<
+
+ 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".
+
+ *nvim_buf_set_extmark()*
+nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts})
+ Creates or updates an extmark.
+
+ To create a new extmark, pass id=0. The extmark id will be
+ returned. It is also allowed to create a new mark by passing
+ in a previously unused id, but the caller must then keep track
+ of existing and unused ids itself. (Useful over RPC, to avoid
+ waiting for the return value.)
+
+ Parameters: ~
+ {buffer} Buffer handle, or 0 for current buffer
+ {ns_id} Namespace id from |nvim_create_namespace()|
+ {id} Extmark id, or 0 to create new
+ {line} Line number where to place the mark
+ {col} Column where to place the mark
+ {opts} Optional parameters. Currently not used.
+
+ Return: ~
+ Id of the created/updated extmark
+
+nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()*
+ Removes an extmark.
+
+ Parameters: ~
+ {buffer} Buffer handle, or 0 for current buffer
+ {ns_id} Namespace id from |nvim_create_namespace()|
+ {id} Extmark id
+
+ Return: ~
+ true if the extmark was found, else false
+
*nvim_buf_add_highlight()*
nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
{col_start}, {col_end})
@@ -1769,8 +1945,8 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
*nvim_buf_clear_namespace()*
nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
- Clears namespaced objects, highlights and virtual text, from a
- line range
+ 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.
@@ -1821,6 +1997,27 @@ 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().
+
+ 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_stats({buffer}) *nvim__buf_stats()*
TODO: Documentation
generated by cgit (git 2.34.1) at 2025-07-24 06:41:02 +0000