diff options
| -rw-r--r-- | runtime/doc/api.txt | 61 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 17 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 6 |
3 files changed, 63 insertions, 21 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index dae7986fdb..18f56ba477 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -127,6 +127,10 @@ 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): @@ -443,6 +447,41 @@ 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. +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: > + + 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) + +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. > + + 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 + +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 + + (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 + + Example: We will set an extmark at the first row and third column. |api-indexing| is @@ -779,10 +818,9 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* On execution error: does not fail, but updates v:errmsg. - If you need to input sequences like <C-o> use - |nvim_replace_termcodes| to replace the termcodes and then - pass the resulting string to nvim_feedkeys. You'll also want - to enable escape_csi. + To input sequences like <C-o> use |nvim_replace_termcodes()| + (typically with escape_csi=true) to replace the keycodes. Then + pass the result to nvim_feedkeys(). Example: > :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) @@ -2072,7 +2110,7 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* *nvim_buf_get_extmark_by_id()* nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) - Returns position for a given extmark id + Gets the position (0-indexed) of an extmark {id}. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -2082,7 +2120,8 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) • details: Whether to include the details dict Return: ~ - (row, col) tuple or empty list () if extmark id was absent + 0-indexed (row, col) tuple or empty list () if extmark id + was absent *nvim_buf_get_extmarks()* nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) @@ -2122,10 +2161,12 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| - {start} Start of range, given as (row, col) or valid - extmark id (whose position defines the bound) - {end} End of range, given as (row, col) or valid - extmark id (whose position defines the bound) + {start} Start of range, given as 0-indexed (row, col) or + valid extmark id (whose position defines the + bound) + {end} End of range (inclusive), given as 0-indexed + (row, col) or valid extmark id (whose position + defines the bound) {opts} Optional parameters. Keys: • limit: Maximum number of marks to return • details Whether to include the details dict diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 878ffdf06f..3260c083b8 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; } -/// Returns position for a given extmark id +/// Gets the position (0-indexed) of an extmark {id}. /// /// @param buffer Buffer handle, or 0 for current buffer /// @param ns_id Namespace id from |nvim_create_namespace()| @@ -1240,7 +1240,8 @@ static Array extmark_to_array(ExtmarkInfo extmark, bool id, bool add_dict) /// @param opts Optional parameters. Keys: /// - details: Whether to include the details dict /// @param[out] err Error details, if any -/// @return (row, col) tuple or empty list () if extmark id was absent +/// @return 0-indexed (row, col) tuple or empty list () if extmark id was +/// absent ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id, Integer id, Dictionary opts, Error *err) @@ -1320,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 (row, col) or valid extmark id -/// (whose position defines the bound) -/// @param end End of range, given as (row, col) or valid extmark id -/// (whose position defines the bound) +/// @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 opts Optional parameters. Keys: /// - limit: Maximum number of marks to return /// - details Whether to include the details dict @@ -1424,8 +1425,8 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, /// /// @param buffer Buffer handle, or 0 for current buffer /// @param ns_id Namespace id from |nvim_create_namespace()| -/// @param line Line where to place the mark, 0-based -/// @param col Column where to place the mark, 0-based +/// @param line Line where to place the mark, 0-based. |api-indexing| +/// @param col Column where to place the mark, 0-based. |api-indexing| /// @param opts Optional parameters. /// - id : id of the extmark to edit. /// - end_line : ending line of the mark, 0-based inclusive. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 5f48a26a29..8f848aba32 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -275,9 +275,9 @@ static void on_redraw_event(void **argv) /// /// On execution error: does not fail, but updates v:errmsg. /// -/// If you need to input sequences like <C-o> use |nvim_replace_termcodes| to -/// replace the termcodes and then pass the resulting string to nvim_feedkeys. -/// You'll also want to enable escape_csi. +/// To input sequences like <C-o> use |nvim_replace_termcodes()| (typically +/// with escape_csi=true) to replace |keycodes|, then pass the result to +/// nvim_feedkeys(). /// /// Example: /// <pre> |