diff options
| -rw-r--r-- | runtime/doc/api.txt | 49 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 2 | ||||
| -rw-r--r-- | src/nvim/ex_cmds.c | 4 |
3 files changed, 28 insertions, 27 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 5d30c10486..4ed0a6aba0 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -441,38 +441,39 @@ Example: create a float with scratch buffer: > ============================================================================== Extended marks *api-extended-marks* -An extended mark (extmark) represents a buffer annotation that follows -movements as the buffer changes. 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. +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. Example: -We will set an extmark at the first row and third column. As the API is zero- -indexed, use row and column counts 0 and 2: +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 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_ns = nvim_create_namespace('myplugin') + let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 0, 2, {}) -Passing in id=0 creates a new mark and returns the id. we can look-up a mark -by its id: +We can get a mark by its id: > -`echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id)` -=> [0, 2] + echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id) + => [0, 2] -Or we can look-up all marks in a buffer for our namespace (or by a range): -`echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, -1)` -=> [[1, 0, 2]] +We can get all marks in a buffer for our namespace (or by a range): > -Deleting the text all around an extended mark does not remove it. If you want -to remove an extended mark, use the |nvim_buf_del_extmark()| function. + echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, -1) + => [[1, 0, 2]] -The namespace ensures your plugin doesn't have to deal with extmarks created -by another plugin. +Deleting all text surrounding an extmark does not remove the extmark. To +remove an extmark use |nvim_buf_del_extmark()|. -Mark positions changed by an edit will be restored on undo/redo. Creating and -deleting marks doesn't count as a buffer change on itself, i e new undo -states will not be created only for marks. +Namespaces allow your 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 +and deleting extmarks is not a buffer change, thus new undo states are not +created for extmark changes. ============================================================================== Global Functions *api-global* @@ -1820,10 +1821,10 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) {upper} One of: extmark id, (row, col) or 0, -1 for buffer ends {opts} additional options. Supports the keys: - • amount: Maximum number of marks to return • + • amount: Maximum number of marks to return Return: ~ - [[nsmark_id, row, col], ...] + [[extmark_id, row, col], ...] *nvim_buf_set_extmark()* nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 5909fd7c02..58011702ac 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -1058,7 +1058,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id, /// @param opts additional options. Supports the keys: /// - amount: Maximum number of marks to return /// @param[out] err Details of an error that may have occurred -/// @return [[nsmark_id, row, col], ...] +/// @return [[extmark_id, row, col], ...] Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object end, Dictionary opts, Error *err) diff --git a/src/nvim/ex_cmds.c b/src/nvim/ex_cmds.c index c5f7815fc5..4725246764 100644 --- a/src/nvim/ex_cmds.c +++ b/src/nvim/ex_cmds.c @@ -3457,9 +3457,9 @@ static buf_T *do_sub(exarg_T *eap, proftime_T timeout, linenr_T newline_in_pat = 0; linenr_T newline_in_sub = 0; - // inccomand tests fail without this check + // inccommand tests fail without this check if (!preview) { - // Requried for Undo to work for nsmarks, + // Required for Undo to work for extmarks. u_save_cursor(); } |