diff options
Diffstat (limited to 'src/nvim/api/buffer.c')
| -rw-r--r-- | src/nvim/api/buffer.c | 119 |
1 files changed, 71 insertions, 48 deletions
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 39330690e8..5df0f0bb47 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -51,8 +51,7 @@ /// /// @param buffer Buffer handle /// @param[out] err Error details, if any -/// @return Line count, or \`0` if the buffer has been unloaded (see -/// |api-buffer|). +/// @return Line count, or 0 for unloaded buffer. |api-buffer| Integer nvim_buf_line_count(Buffer buffer, Error *err) FUNC_API_SINCE(1) { @@ -227,8 +226,7 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer, /// @param end Last line index (exclusive) /// @param strict_indexing Whether out-of-bounds should be an error. /// @param[out] err Error details, if any -/// @return Array of lines. If the buffer has been unloaded then an empty array -/// will be returned instead. (See |api-buffer|.) +/// @return Array of lines, or empty array for unloaded buffer. ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id, Buffer buffer, Integer start, @@ -491,12 +489,12 @@ end: try_end(err); } -/// Return the byte offset for a line. -// -/// The first line returns 0. UTF-8 bytes are counted, and EOL counts as one -/// byte. 'fileformat' and 'fileencoding' are ignored. Sending in the index -/// just below the last line gives the total byte count for the entire buffer. -/// A final EOL is included if it would be written, see 'eol'. +/// Returns the byte offset for a line. +/// +/// 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'. /// /// Unlike |line2byte()|, throws error for out-of-bounds indexing. /// Returns -1 for unloaded buffer. @@ -504,7 +502,7 @@ end: /// @param buffer Buffer handle /// @param index Line index /// @param[out] err Error details, if any -/// @return Integer Byte offset +/// @return Integer byte offset, or -1 for unloaded buffer. Integer nvim_buf_get_offset(Buffer buffer, Integer index, Error *err) FUNC_API_SINCE(5) { @@ -907,34 +905,34 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err) /// /// 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 +/// 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. /// -/// `src_id` is useful for batch deletion/updating of a set of highlights. When -/// called with `src_id = 0`, an unique source id is generated and returned. -/// Successive calls can pass that `src_id` to associate new highlights with -/// the same source group. All highlights in the same group can be cleared -/// with `nvim_buf_clear_highlight`. If the highlight never will be manually -/// deleted, pass `src_id = -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`. /// -/// If `hl_group` is the empty string no highlight is added, but a new `src_id` -/// is still returned. This is useful for an external plugin to synchrounously -/// request an unique `src_id` at initialization, and later asynchronously add -/// and clear highlights in response to buffer changes. +/// 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. /// /// @param buffer Buffer handle -/// @param src_id Source group to use or 0 to use a new group, -/// or -1 for ungrouped highlight +/// @param ns_id namespace to use or -1 for ungrouped highlight /// @param hl_group Name of the highlight group to use /// @param line Line to highlight (zero-indexed) /// @param col_start Start of (byte-indexed) column range to highlight /// @param col_end End of (byte-indexed) column range to highlight, /// or -1 to highlight to end of line /// @param[out] err Error details, if any -/// @return The src_id that was used +/// @return The ns_id that was used Integer nvim_buf_add_highlight(Buffer buffer, - Integer src_id, + Integer ns_id, String hl_group, Integer line, Integer col_start, @@ -964,28 +962,28 @@ Integer nvim_buf_add_highlight(Buffer buffer, hlg_id = syn_check_group((char_u *)hl_group.data, (int)hl_group.size); } - src_id = bufhl_add_hl(buf, (int)src_id, hlg_id, (linenr_T)line+1, - (colnr_T)col_start+1, (colnr_T)col_end); - return src_id; + ns_id = bufhl_add_hl(buf, (int)ns_id, hlg_id, (linenr_T)line+1, + (colnr_T)col_start+1, (colnr_T)col_end); + return ns_id; } -/// Clears highlights and virtual text from a given source id and range of lines +/// Clears namespaced objects, highlights and virtual text, from a line range /// -/// To clear a source group in the entire buffer, pass in 0 and -1 to +/// To clear the namespace in the entire buffer, pass in 0 and -1 to /// line_start and line_end respectively. /// /// @param buffer Buffer handle -/// @param src_id Highlight source group to clear, or -1 to clear all. +/// @param ns_id Namespace to clear, or -1 to clear all namespaces. /// @param line_start Start of range of lines to clear /// @param line_end End of range of lines to clear (exclusive) or -1 to clear -/// to end of file. +/// to end of buffer. /// @param[out] err Error details, if any -void nvim_buf_clear_highlight(Buffer buffer, - Integer src_id, +void nvim_buf_clear_namespace(Buffer buffer, + Integer ns_id, Integer line_start, Integer line_end, Error *err) - FUNC_API_SINCE(1) + FUNC_API_SINCE(5) { buf_T *buf = find_buffer_by_handle(buffer, err); if (!buf) { @@ -1000,7 +998,27 @@ void nvim_buf_clear_highlight(Buffer buffer, line_end = MAXLNUM; } - bufhl_clear_line_range(buf, (int)src_id, (int)line_start+1, (int)line_end); + bufhl_clear_line_range(buf, (int)ns_id, (int)line_start+1, (int)line_end); +} + +/// Clears highlights and virtual text from namespace and range of lines +/// +/// @deprecated use |nvim_buf_clear_namespace|. +/// +/// @param buffer Buffer handle +/// @param ns_id Namespace to clear, or -1 to clear all. +/// @param line_start Start of range of lines to clear +/// @param line_end End of range of lines to clear (exclusive) or -1 to clear +/// to end of file. +/// @param[out] err Error details, if any +void nvim_buf_clear_highlight(Buffer buffer, + Integer ns_id, + Integer line_start, + Integer line_end, + Error *err) + FUNC_API_SINCE(1) +{ + nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end, err); } @@ -1009,15 +1027,20 @@ void nvim_buf_clear_highlight(Buffer buffer, /// By default (and currently the only option) the text will be placed after /// the buffer text. Virtual text will never cause reflow, rather virtual /// text will be truncated at the end of the screen line. The virtual text will -/// begin after one cell to the right of the ordinary text, this will contain -/// the |lcs-eol| char if set, otherwise just be a space. +/// begin one cell (|lcs-eol| or space) after the ordinary text. +/// +/// 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 +/// 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`. /// -/// The same src_id can be used for both virtual text and highlights added by -/// nvim_buf_add_highlight. Virtual text is cleared using -/// nvim_buf_clear_highlight. +/// As a shorthand, `ns_id = 0` can be used to create a new namespace for the +/// virtual text, the allocated id is then returned. /// /// @param buffer Buffer handle -/// @param src_id Source group to use or 0 to use a new group, +/// @param ns_id Namespace to use or 0 to create a namespace, /// or -1 for a ungrouped annotation /// @param line Line to annotate with virtual text (zero-indexed) /// @param chunks A list of [text, hl_group] arrays, each representing a @@ -1025,9 +1048,9 @@ void nvim_buf_clear_highlight(Buffer buffer, /// can be omitted for no highlight. /// @param opts Optional parameters. Currently not used. /// @param[out] err Error details, if any -/// @return The src_id that was used +/// @return The ns_id that was used Integer nvim_buf_set_virtual_text(Buffer buffer, - Integer src_id, + Integer ns_id, Integer line, Array chunks, Dictionary opts, @@ -1077,9 +1100,9 @@ Integer nvim_buf_set_virtual_text(Buffer buffer, kv_push(virt_text, ((VirtTextChunk){ .text = text, .hl_id = hl_id })); } - src_id = bufhl_add_virt_text(buf, (int)src_id, (linenr_T)line+1, - virt_text); - return src_id; + ns_id = bufhl_add_virt_text(buf, (int)ns_id, (linenr_T)line+1, + virt_text); + return ns_id; free_exit: kv_destroy(virt_text); |