Macros | Functions
extmark.c File Reference
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include "nvim/api/extmark.h"
#include "nvim/api/private/defs.h"
#include "nvim/api/private/helpers.h"
#include "nvim/decoration_provider.h"
#include "nvim/extmark.h"
#include "nvim/highlight_group.h"
#include "nvim/lua/executor.h"
#include "nvim/memline.h"
#include "nvim/screen.h"

Macros

#define OPTION_TO_BOOL(target, name, val)
 

Functions

void api_extmark_free_all_mem (void)
 
Integer nvim_create_namespace (String name) FUNC_API_SINCE(5)
 
Dictionary nvim_get_namespaces (void)
 
const char * describe_ns (NS ns_id)
 
 ArrayOf (Integer)
 
Array nvim_buf_get_extmarks (Buffer buffer, Integer ns_id, Object start, Object end, Dictionary opts, Error *err) FUNC_API_SINCE(7)
 
Integer nvim_buf_set_extmark (Buffer buffer, Integer ns_id, Integer line, Integer col, Dict(set_extmark) *opts, Error *err) FUNC_API_SINCE(7)
 
Boolean nvim_buf_del_extmark (Buffer buffer, Integer ns_id, Integer id, Error *err) FUNC_API_SINCE(7)
 
uint32_t src2ns (Integer *src_id)
 
Integer nvim_buf_add_highlight (Buffer buffer, Integer ns_id, String hl_group, Integer line, Integer col_start, Integer col_end, Error *err) FUNC_API_SINCE(1)
 
void nvim_buf_clear_namespace (Buffer buffer, Integer ns_id, Integer line_start, Integer line_end, Error *err) FUNC_API_SINCE(5)
 
void nvim_set_decoration_provider (Integer ns_id, DictionaryOf(LuaRef) opts, Error *err) FUNC_API_SINCE(7) FUNC_API_LUA_ONLY
 

Macro Definition Documentation

◆ OPTION_TO_BOOL

#define OPTION_TO_BOOL (   target,
  name,
  val 
)
Value:
target = api_object_to_bool(opts->name, #name, val, err); \
if (ERROR_SET(err)) { \
goto error; \
}

Function Documentation

◆ api_extmark_free_all_mem()

void api_extmark_free_all_mem ( void  )

◆ ArrayOf()

ArrayOf ( Integer  )

Gets the position (0-indexed) of an extmark.

Parameters
bufferBuffer handle, or 0 for current buffer
ns_idNamespace id from |nvim_create_namespace()|
idExtmark id
optsOptional parameters. Keys:
  • details: Whether to include the details dict
[out]errError details, if any
Returns
0-indexed (row, col) tuple or empty list () if extmark id was absent

◆ describe_ns()

const char* describe_ns ( NS  ns_id)

◆ nvim_buf_add_highlight()

Integer nvim_buf_add_highlight ( Buffer  buffer,
Integer  ns_id,
String  hl_group,
Integer  line,
Integer  col_start,
Integer  col_end,
Error err 
)

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
bufferBuffer handle, or 0 for current buffer
ns_idnamespace to use or -1 for ungrouped highlight
hl_groupName of the highlight group to use
lineLine to highlight (zero-indexed)
col_startStart of (byte-indexed) column range to highlight
col_endEnd of (byte-indexed) column range to highlight, or -1 to highlight to end of line
[out]errError details, if any
Returns
The ns_id that was used

◆ nvim_buf_clear_namespace()

void nvim_buf_clear_namespace ( Buffer  buffer,
Integer  ns_id,
Integer  line_start,
Integer  line_end,
Error err 
)

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
bufferBuffer handle, or 0 for current buffer
ns_idNamespace to clear, or -1 to clear all namespaces.
line_startStart of range of lines to clear
line_endEnd of range of lines to clear (exclusive) or -1 to clear to end of buffer.
[out]errError details, if any

◆ nvim_buf_del_extmark()

Boolean nvim_buf_del_extmark ( Buffer  buffer,
Integer  ns_id,
Integer  id,
Error err 
)

Removes an extmark.

Parameters
bufferBuffer handle, or 0 for current buffer
ns_idNamespace id from |nvim_create_namespace()|
idExtmark id
[out]errError details, if any
Returns
true if the extmark was found, else false

◆ nvim_buf_get_extmarks()

Array nvim_buf_get_extmarks ( Buffer  buffer,
Integer  ns_id,
Object  start,
Object  end,
Dictionary  opts,
Error err 
)

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, {})
  -- Create new extmark at line 3, column 1.
  local m2  = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
  -- 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
bufferBuffer handle, or 0 for current buffer
ns_idNamespace id from |nvim_create_namespace()|
startStart of range: a 0-indexed (row, col) or valid extmark id (whose position defines the bound). |api-indexing|
endEnd of range (inclusive): a 0-indexed (row, col) or valid extmark id (whose position defines the bound). |api-indexing|
optsOptional parameters. Keys:
  • limit: Maximum number of marks to return
  • details Whether to include the details dict
[out]errError details, if any
Returns
List of [extmark_id, row, col] tuples in "traversal order".

◆ nvim_buf_set_extmark()

Integer nvim_buf_set_extmark ( Buffer  buffer,
Integer  ns_id,
Integer  line,
Integer  col,
Dict(set_extmark) *  opts,
Error err 
)

Creates or updates an extmark.

To create a new extmark, pass id=0. The extmark id will be 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
bufferBuffer handle, or 0 for current buffer
ns_idNamespace id from |nvim_create_namespace()|
lineLine where to place the mark, 0-based. |api-indexing|
colColumn where to place the mark, 0-based. |api-indexing|
optsOptional parameters.
  • id : id of the extmark to edit.
  • end_row : ending line of the mark, 0-based inclusive.
  • end_col : ending col of the mark, 0-based exclusive.
  • hl_group : name of the highlight group used to highlight this mark.
  • hl_eol : when true, for a multiline highlight covering the EOL of a line, continue the highlight for the rest of the screen line (just like for diff and cursorline highlight).
  • virt_text : virtual text to link to this mark. A list of [text, highlight] tuples, each representing a text chunk with specified highlight. highlight element can either be a a single highlight group, or an array of multiple highlight groups that will be stacked (highest priority last). A highlight group can be supplied either as a string or as an integer, the latter which can be obtained using |nvim_get_hl_id_by_name|.
  • virt_text_pos : position of virtual text. Possible values:
    • "eol": right after eol character (default)
    • "overlay": display over the specified column, without shifting the underlying text.
    • "right_align": display right aligned in the window.
  • virt_text_win_col : position the virtual text at a fixed window column (starting from the first text column)
  • virt_text_hide : hide the virtual text when the background text is selected or hidden due to horizontal scroll 'nowrap'
  • hl_mode : control how highlights are combined with the highlights of the text. Currently only affects virt_text highlights, but might affect hl_group in later versions.
    • "replace": only show the virt_text color. This is the default
    • "combine": combine with background text color
    • "blend": blend with background text color.
  • virt_lines : virtual lines to add next to this mark This should be an array over lines, where each line in turn is an array over [text, highlight] tuples. In general, buffer and window options do not affect the display of the text. In particular 'wrap' and 'linebreak' options do not take effect, so the number of extra screen lines will always match the size of the array. However the 'tabstop' buffer option is still used for hard tabs. By default lines are placed below the buffer line containing the mark.
  • virt_lines_above: place virtual lines above instead.
  • virt_lines_leftcol: Place extmarks in the leftmost column of the window, bypassing sign and number columns.
  • 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.
  • right_gravity : boolean that indicates the direction the extmark will be shifted in when new text is inserted (true for right, false for left). defaults to true.
  • end_right_gravity : boolean that indicates the direction the extmark end position (if it exists) will be shifted in when new text is inserted (true for right, false for left). Defaults to false.
  • priority: a priority value for the highlight group. For example treesitter highlighting uses a value of 100.
  • strict: boolean that indicates extmark should not be placed if the line or column value is past the end of the buffer or end of the line respectively. Defaults to true.
  • sign_text: string of length 1-2 used to display in the sign column. Note: ranges are unsupported and decorations are only applied to start_row
  • sign_hl_group: name of the highlight group used to highlight the sign column text. Note: ranges are unsupported and decorations are only applied to start_row
  • number_hl_group: name of the highlight group used to highlight the number column. Note: ranges are unsupported and decorations are only applied to start_row
  • line_hl_group: name of the highlight group used to highlight the whole line. Note: ranges are unsupported and decorations are only applied to start_row
  • cursorline_hl_group: name of the highlight group used to highlight the line when the cursor is on the same line as the mark and 'cursorline' is enabled. Note: ranges are unsupported and decorations are only applied to start_row
  • conceal: string which should be either empty or a single character. Enable concealing similar to |:syn-conceal|. When a character is supplied it is used as |:syn-cchar|. "hl_group" is used as highlight for the cchar if provided, otherwise it defaults to |hl-Conceal|.
  • ui_watched: boolean that indicates the mark should be drawn by a UI. When set, the UI will receive win_extmark events. Note: the mark is positioned by virt_text attributes. Can be used together with virt_text.
[out]errError details, if any
Returns
Id of the created/updated extmark

◆ nvim_create_namespace()

Integer nvim_create_namespace ( String  name)

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_extmark()|.

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
nameNamespace name or empty string
Returns
Namespace id

◆ nvim_get_namespaces()

Dictionary nvim_get_namespaces ( void  )

Gets existing, non-anonymous namespaces.

Returns
dict that maps from names to namespace ids.

◆ nvim_set_decoration_provider()

void nvim_set_decoration_provider ( Integer  ns_id,
DictionaryOf(LuaRef opts,
Error err 
)

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. Similarly, 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 decoration 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_idNamespace id from |nvim_create_namespace()|
optsCallbacks 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 interaction with fold lines is subject to change) ["win", winid, bufnr, row]
  • on_end: called at the end of a redraw cycle ["end", tick]

◆ src2ns()

uint32_t src2ns ( Integer src_id)
api_object_to_bool
bool api_object_to_bool(Object obj, const char *what, bool nil_value, Error *err)
Definition: helpers.c:1291
name
char_u * name
Definition: userfunc.c:817
ERROR_SET
#define ERROR_SET(e)
Definition: defs.h:17