From b96730bc3bc71e03004b9720bcd0ac67a2a7bb85 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 5 Nov 2018 03:50:22 +0100 Subject: doc: API --- src/nvim/api/buffer.c | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) (limited to 'src/nvim/api/buffer.c') diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 39330690e8..487a912882 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) { -- cgit From 01dbf0951b25d582451a8e656731dcf3d9295a71 Mon Sep 17 00:00:00 2001 From: Björn Linse Date: Fri, 23 Jun 2017 09:56:35 +0200 Subject: api: implement object namespaces Namespaces is a lightweight concept that should be used to group objects for purposes of bulk operations and introspection. This is initially used for highlights and virtual text in buffers, and is planned to also be used for extended marks. There is no plan use them for privileges or isolation, neither to introduce nanespace-level options. --- src/nvim/api/buffer.c | 66 ++++++++++++++++++++++++++++----------------------- 1 file changed, 36 insertions(+), 30 deletions(-) (limited to 'src/nvim/api/buffer.c') diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 487a912882..4559f37191 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -905,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_highlight|. 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, @@ -962,9 +962,9 @@ 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 @@ -973,13 +973,13 @@ Integer nvim_buf_add_highlight(Buffer buffer, /// 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. /// @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 src_id, + Integer ns_id, Integer line_start, Integer line_end, Error *err) @@ -998,7 +998,7 @@ 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); } @@ -1010,12 +1010,18 @@ void nvim_buf_clear_highlight(Buffer buffer, /// 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. /// -/// 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. +/// 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_highlight|. 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_highlight|. If the +/// virtual text never will be cleared by an API call, pass `src_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 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 @@ -1023,9 +1029,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, @@ -1075,9 +1081,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); -- cgit From 32405de7df965174f0aad19692b8d988bae83a44 Mon Sep 17 00:00:00 2001 From: Björn Linse Date: Thu, 29 Nov 2018 15:08:40 +0100 Subject: API: rename nvim_buf_clear_highlight to nvim_buf_clear_namespace We want a single function to clear all namespaced buffer objects. This will later include extmarks. --- src/nvim/api/buffer.c | 40 ++++++++++++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 10 deletions(-) (limited to 'src/nvim/api/buffer.c') diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 4559f37191..29c8ea634a 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -913,7 +913,7 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err) /// 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_highlight|. If the highlight never will be +/// 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 @@ -967,23 +967,23 @@ Integer nvim_buf_add_highlight(Buffer buffer, 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 ns_id Namespace 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, +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) { @@ -1001,6 +1001,26 @@ void nvim_buf_clear_highlight(Buffer buffer, 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); +} + /// Set the virtual text (annotation) for a buffer line. /// @@ -1012,10 +1032,10 @@ void nvim_buf_clear_highlight(Buffer buffer, /// /// 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_highlight|. The same `ns_id` can be used for +/// 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_highlight|. If the -/// virtual text never will be cleared by an API call, pass `src_id = -1`. +/// 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 returned. -- cgit From 857a7312d015350c9637548310c7a187637d3ca4 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 9 Dec 2018 01:31:34 +0100 Subject: doc (#9288) - misc - doc: `:help config`. closes #9329 - cleanup test/README.md --- src/nvim/api/buffer.c | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'src/nvim/api/buffer.c') diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 29c8ea634a..5df0f0bb47 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -1027,8 +1027,7 @@ 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 -- cgit