From 4de70f5b9581bd0e35e7af3b6fb1eb835d538555 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 1 Nov 2018 05:24:44 +0100 Subject: doc - update standard-plugin-list. closes #8388 --- src/nvim/api/vim.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/nvim/api') diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index fed20a272a..7fcccfd988 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1028,7 +1028,7 @@ Array nvim_get_api_info(uint64_t channel_id) /// @param attributes Informal attributes describing the client. Clients might /// define their own keys, but the following are suggested: /// - "website" Website of client (for instance github repository) -/// - "license" Informal descripton of the license, such as "Apache 2", +/// - "license" Informal description of the license, such as "Apache 2", /// "GPLv3" or "MIT" /// - "logo" URI or path to image, preferably small logo or icon. /// .png or .svg format is preferred. -- cgit 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') 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 ++++++++++++++++++++++++++++----------------------- src/nvim/api/vim.c | 61 +++++++++++++++++++++++++++++++++++++++++++++++ src/nvim/api/vim.h | 4 ++++ 3 files changed, 101 insertions(+), 30 deletions(-) (limited to 'src/nvim/api') 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); diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 7fcccfd988..54b27477e0 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -46,6 +46,24 @@ # include "api/vim.c.generated.h" #endif +void api_vim_init(void) + FUNC_API_NOEXPORT +{ + namespace_ids = map_new(String, handle_T)(); +} + +void api_vim_free_all_mem(void) + FUNC_API_NOEXPORT +{ + String name; + handle_T id; + map_foreach(namespace_ids, name, id, { + (void)id; + xfree(name.data); + }) + map_free(String, handle_T)(namespace_ids); +} + /// Executes an ex-command. /// /// On execution error: fails with VimL error, does not update v:errmsg. @@ -884,6 +902,49 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err) } } +/// create a new namespace, or get one with an exisiting name +/// +/// Namespaces are currently used for buffer highlighting and virtual text, see +/// |nvim_buf_add_highlight| and |nvim_buf_set_virtual_text|. +/// +/// Namespaces can have a name of be anonymous. If `name` is a non-empty string, +/// and a namespace already exists with that name,the existing namespace id is +/// returned. If an empty string is used, a new anonymous namespace is returned. +/// +/// @param name Name of the namespace or empty string +/// @return the namespace id +Integer nvim_create_namespace(String name) + FUNC_API_SINCE(5) +{ + handle_T id = map_get(String, handle_T)(namespace_ids, name); + if (id > 0) { + return id; + } + id = next_namespace_id++; + if (name.size > 0) { + String name_alloc = copy_string(name); + map_put(String, handle_T)(namespace_ids, name_alloc, id); + } + return (Integer)id; +} + +/// Get existing named namespaces +/// +/// @return dict that maps from names to namespace ids. +Dictionary nvim_get_namespaces(void) + FUNC_API_SINCE(5) +{ + Dictionary retval = ARRAY_DICT_INIT; + String name; + handle_T id; + + map_foreach(namespace_ids, name, id, { + PUT(retval, name.data, INTEGER_OBJ(id)); + }) + + return retval; +} + /// Subscribes to event broadcasts /// /// @param channel_id Channel id (passed automatically by the dispatcher) diff --git a/src/nvim/api/vim.h b/src/nvim/api/vim.h index 5e0b35b562..d6873da6d2 100644 --- a/src/nvim/api/vim.h +++ b/src/nvim/api/vim.h @@ -4,6 +4,10 @@ #include #include "nvim/api/private/defs.h" +#include "nvim/map.h" + +EXTERN Map(String, handle_T) *namespace_ids INIT(= NULL); +EXTERN handle_T next_namespace_id INIT(= 1); #ifdef INCLUDE_GENERATED_DECLARATIONS # include "api/vim.h.generated.h" -- cgit From b1aaa0a881ef36676ddd71e7308ae7461c62896d Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 25 Nov 2018 16:27:10 +0100 Subject: API: Implement nvim_win_set_buf() #9100 closes #9100 --- src/nvim/api/window.c | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'src/nvim/api') diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c index 5281a7c1f4..cf1d1f5e45 100644 --- a/src/nvim/api/window.c +++ b/src/nvim/api/window.c @@ -10,6 +10,7 @@ #include "nvim/api/private/defs.h" #include "nvim/api/private/helpers.h" #include "nvim/vim.h" +#include "nvim/buffer.h" #include "nvim/cursor.h" #include "nvim/window.h" #include "nvim/screen.h" @@ -33,6 +34,41 @@ Buffer nvim_win_get_buf(Window window, Error *err) return win->w_buffer->handle; } +/// Sets the current buffer in a window, without side-effects +/// +/// @param window Window handle +/// @param buffer Buffer handle +/// @param[out] err Error details, if any +void nvim_win_set_buf(Window window, Buffer buffer, Error *err) + FUNC_API_SINCE(5) +{ + win_T *win = find_window_by_handle(window, err), *save_curwin = curwin; + buf_T *buf = find_buffer_by_handle(buffer, err); + tabpage_T *tab = win_find_tabpage(win), *save_curtab = curtab; + + if (!win || !buf) { + return; + } + + if (switch_win(&save_curwin, &save_curtab, win, tab, false) == FAIL) { + api_set_error(err, + kErrorTypeException, + "Failed to switch to window %d", + window); + } + + try_start(); + int result = do_buffer(DOBUF_GOTO, DOBUF_FIRST, FORWARD, buf->b_fnum, 0); + if (!try_end(err) && result == FAIL) { + api_set_error(err, + kErrorTypeException, + "Failed to set buffer %d", + buffer); + } + + restore_win(save_curwin, save_curtab, false); +} + /// Gets the cursor position in the window /// /// @param window Window handle -- cgit From 30857030e848e4a727a889e51d4618ab9b30651f Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 16 Nov 2018 02:00:04 +0100 Subject: doc - develop.txt is for design/guidelines; architecture/concepts should live elsewhere (currently src/nvim/README.md) - move dev-jargon to intro.txt - replace https://neovim.io/community (deprecated) with https://neovim.io/#chat - avoids CmdlineEnter/Leave https://github.com/vim/vim/issues/2889 --- src/nvim/api/vim.c | 3 +++ 1 file changed, 3 insertions(+) (limited to 'src/nvim/api') diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 54b27477e0..4da61a30ef 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -743,6 +743,9 @@ void nvim_err_writeln(String str) /// Gets the current list of buffer handles /// +/// Includes unlisted (unloaded/deleted) buffers, like `:ls!`. +/// Use |nvim_buf_is_loaded()| to check if a buffer is loaded. +/// /// @return List of buffer handles ArrayOf(Buffer) nvim_list_bufs(void) FUNC_API_SINCE(1) -- 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') 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') 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