diff options
| -rw-r--r-- | runtime/doc/api.txt | 40 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 10 |
2 files changed, 35 insertions, 15 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 18f56ba477..6247aab550 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -127,10 +127,6 @@ Special types (msgpack EXT) ~ Most of the API uses 0-based indices, and ranges are end-exclusive. For the end of a range, -1 denotes the last line/column. -Exception: the following API functions use 0-based, end-inclusive indexing: - - |nvim_buf_get_extmarks()| - Exception: the following API functions use "mark-like" indexing (1-based lines, 0-based columns): @@ -138,6 +134,14 @@ lines, 0-based columns): |nvim_win_get_cursor()| |nvim_win_set_cursor()| +Exception: the following API functions use |extmarks| indexing (0-based lines, +0-based columns end-inclusive): + + |nvim_buf_del_extmark()| + |nvim_buf_get_extmark_by_id()| + |nvim_buf_get_extmarks()| + |nvim_buf_set_extmark()| + *api-fast* Most API functions are "deferred": they are queued on the main loop and processed sequentially with normal input. So if the editor is waiting for @@ -440,12 +444,13 @@ Example: create a float with scratch buffer: > > ============================================================================== -Extended marks *api-extended-marks* +Extended marks *api-extended-marks* *extmarks* 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. +over time. It is useful to think of an extmark position to be in the space +between characters. Extmarks use |api-indexing|, and you can think of them as cursor positions. For example, an extmark at position 1 exists between the first and second @@ -488,12 +493,16 @@ 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: > + 01 2345678 + 0 ex|ample.. +< ^ This is the extmark position +> let g:mark_ns = nvim_create_namespace('myplugin') - let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 0, 2, {}) - + let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {}) +< We can get a mark by its id: > - echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_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): > @@ -502,7 +511,18 @@ We can get all marks in a buffer for our namespace (or by a range): > => [[1, 0, 2]] Deleting all text surrounding an extmark does not remove the extmark. To -remove an extmark use |nvim_buf_del_extmark()|. +remove an extmark use |nvim_buf_del_extmark()|. Deleting "x" in our example +would result in the following: > + + 0 12345678 + 0 e|ample.. +< ^ This is the extmark position +> + echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {}) + => [0, 1] +< + Note: An extmark "gravity" is the direction it will be shifted after a + text edit. See |nvim_buf_set_extmark()| for more information. Namespaces allow your plugin to manage only its own extmarks, ignoring those created by another plugin. diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 3260c083b8..3808f601d9 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -1232,7 +1232,7 @@ static Array extmark_to_array(ExtmarkInfo extmark, bool id, bool add_dict) return rv; } -/// Gets the position (0-indexed) of an extmark {id}. +/// Gets the position (0-indexed) of an extmark. /// /// @param buffer Buffer handle, or 0 for current buffer /// @param ns_id Namespace id from |nvim_create_namespace()| @@ -1321,10 +1321,10 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id, /// /// @param buffer Buffer handle, or 0 for current buffer /// @param ns_id Namespace id from |nvim_create_namespace()| -/// @param start Start of range, given as 0-indexed (row, col) or valid -/// extmark id (whose position defines the bound) -/// @param end End of range (inclusive), given as 0-indexed (row, col) or -/// valid extmark id (whose position defines the bound) +/// @param start Start of range: a 0-indexed (row, col) or valid extmark id +/// (whose position defines the bound). |api-indexing| +/// @param end End of range (inclusive): a 0-indexed (row, col) or valid +/// extmark id (whose position defines the bound). |api-indexing| /// @param opts Optional parameters. Keys: /// - limit: Maximum number of marks to return /// - details Whether to include the details dict |