IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-02-25 18:55:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: extmarks indexing #15311

Browse Source 
fix #11456
This commit is contained in:
Javier López 2021-08-08 16:17:23 -05:00 committed by Justin M. Keyes
parent 9b553ad28d
commit f8e406ed30
2 changed files with 35 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
runtime/doc/api.txt
View File

@ -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.

10
src/nvim/api/buffer.c
View File

@ -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