diff options
| -rw-r--r-- | runtime/doc/api.txt | 79 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 2 |
2 files changed, 35 insertions, 46 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 6247aab550..df345e4981 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -134,8 +134,8 @@ 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): +Exception: the following API functions use |extmarks| indexing (0-based +indices, end-inclusive): |nvim_buf_del_extmark()| |nvim_buf_get_extmark_by_id()| @@ -447,84 +447,73 @@ Example: create a float with scratch buffer: > 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. It is useful to think of an extmark position to be in the space -between characters. +in the buffer. They can represent cursors, folds, misspelled words, anything +that needs to track a logical location in the buffer over time. |api-indexing| -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 -character on a line, similar to a bar cursor. For that reason, the maximum -extmark index on a line is 1 larger than the character index: > +Extmark position works like "bar" cursor: it exists between characters. Thus +the maximum extmark index on a line is 1 more than the character index: > - f o o b a r <-- line contents (with spaces for illustration purposes) - 0 1 2 3 4 5 <-- character positions (0-based) - 0 1 2 3 4 5 6 <-- extmark positions (0-based) + f o o b a r line contents + 0 1 2 3 4 5 character positions (0-based) + 0 1 2 3 4 5 6 extmark positions (0-based) -Note that extmarks have "forward gravity": If you place the cursor directly on -an extmark position and enter some text, the extmark gets pushed forward. > +Extmarks have "forward gravity": if you place the cursor directly on an +extmark position and enter some text, the extmark migrates forward. > - f o o|b a r <-- line (| = cursor) - 3 <-- extmark + f o o|b a r line (| = cursor) + 3 extmark - (Now add "z" at cursor position): + f o o z|b a r line (| = cursor) + 4 extmark (after typing "z") - f o o z|b a r <-- line (| = cursor) - 4 <-- extmark +If an extmark is on the last index of a line and you inputsa newline at that +point, the extmark will accordingly migrate to the next line: > -If your extmark is on the last possible index of a line (7 in the above -"foozbar" example) and you enter a newline at that point, the extmark will -accordingly be pushed to the next line: > + f o o z b a r| line (| = cursor) + 7 extmark - f o o z b a r| <-- line (| = cursor) - 7 <-- extmark - - (Now add <cr> at cursor position): - - f o o z b a r <-- first line - <-- extmarks (none present) - | <-- second line (| = cursor) - 0 <-- new extmark position + f o o z b a r first line + extmarks (none present) + | second line (| = cursor) + 0 extmark (after typing <CR>) Example: -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: > +Let's set an extmark at the first row (row=0) and third column (column=2). +|api-indexing| Passing id=0 creates a new mark and returns the id: > 01 2345678 0 ex|ample.. -< ^ This is the extmark position +< ^ extmark position > let g:mark_ns = nvim_create_namespace('myplugin') let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {}) < -We can get a mark by its id: > +We can get the mark by its 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): > +We can get all marks in a buffer by |namespace| (or by a range): > echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {}) => [[1, 0, 2]] -Deleting all text surrounding an extmark does not remove the extmark. To -remove an extmark use |nvim_buf_del_extmark()|. Deleting "x" in our example -would result in the following: > +Deleting all surrounding text does NOT remove an extmark! To remove extmarks +use |nvim_buf_del_extmark()|. Deleting "x" in our example: > 0 12345678 0 e|ample.. -< ^ This is the extmark position +< ^ 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. + Note: Extmark "gravity" decides how it will shift after a text edit. + See |nvim_buf_set_extmark()| -Namespaces allow your plugin to manage only its own extmarks, ignoring those +Namespaces allow any plugin to manage only its own extmarks, ignoring those created by another plugin. Extmark positions changed by an edit will be restored on undo/redo. Creating diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 8f848aba32..f65d5cc185 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1551,7 +1551,7 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err) } } -/// Creates a new namespace, or gets an existing one. +/// 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()|. |