diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 130 |
1 files changed, 100 insertions, 30 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index d6b7938633..5d30c10486 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -439,34 +439,40 @@ Example: create a float with scratch buffer: > > ============================================================================== -Buffer extended marks *api-extended-marks* +Extended marks *api-extended-marks* -An extended mark represents a buffer annotation that remains logically -stationary even as the buffer changes. They could be used to represent cursors, +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. Example: -We will set an extmark at row 1, column three. +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: `let g:mark_ns = nvim_create_namespace('myplugin')` -`let g:mark_id = nvim_buf_set_mark(0, :g:mark_ns, 0, 1, 3)` +`let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 0, 2)` -Note: the mark id was randomly generated because we used an inital value of 0 +Passing in id=0 creates a new mark and returns the id. we can look-up a mark +by its id: -`echo nvim_buf_lookup_mark(0, g:mark_ns, g:mark_id)` -=> [1, 1, 3] -`echo nvim_buf_get_marks(0, g:mark_ns, [1, 1], [1, 3], -1, 0)` -=> [[1, 1, 3]] +`echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id)` +=> [0, 2] -Deleting the text all around an extended mark does not remove it. If you want -to remove an extended mark, use the |nvim_buf_unset_mark()| function. +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]] -The namepsace ensures you only ever work with the extended marks you mean to. +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. -Calling set and unset of marks will not automatically prop a new undo. +The namespace ensures your plugin doesn't have to deal with extmarks created +by another plugin. +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. ============================================================================== Global Functions *api-global* @@ -1479,22 +1485,6 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* TODO: Documentation - *nvim_init_mark_ns()* -nvim_init_mark_ns({namespace}) - Create a new namepsace for holding extended marks. The id - of the namespace is returned, this namespace id is required - for using the rest of the extended marks api. - - Parameters:~ - {namespace} String name to be assigned to the namespace - - - *nvim_mark_get_ns_ids()* -nvim_mark_get_ns_ids() - Returns a list of extended mark namespaces. - Pairs of ids and string names are returned. - An empty list will be returned if no namespaces are set. - ============================================================================== Buffer Functions *api-buffer* @@ -1793,6 +1783,86 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* Return: ~ (row, col) tuple + *nvim_buf_get_extmark_by_id()* +nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}) + Returns position for a given extmark id + + Parameters: ~ + {buffer} The buffer handle + {namespace} a identifier returned previously with + nvim_create_namespace + {id} the extmark id + + Return: ~ + (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}) + List extmarks in a range (inclusive) + + range ends can be specified as (row, col) tuples, as well as + extmark ids in the same namespace. In addition, 0 and -1 works + as shorthands for (0,0) and (-1,-1) respectively, so that all + marks in the buffer can be quieried as: + + all_marks = nvim_buf_get_extmarks(0, my_ns, 0, -1, -1) + + If end is a lower position than start, then the range will be + traversed backwards. This is mostly used with limited amount, + to be able to get the first marks prior to a given position. + + Parameters: ~ + {buffer} The buffer handle + {ns_id} An id returned previously from + nvim_create_namespace + {lower} One of: extmark id, (row, col) or 0, -1 for + buffer ends + {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 • + + Return: ~ + [[nsmark_id, row, col], ...] + + *nvim_buf_set_extmark()* +nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) + Create or update an extmark at a position + + If an invalid namespace is given, an error will be raised. + + To create a new extmark, pass in id=0. The new extmark id will + be returned. To move an existing mark, pass in its id. + + It is also allowed to create a new mark by passing in a + previously unused id, but the caller must then keep track of + existing and unused ids itself. This is mainly useful over + RPC, to avoid needing to wait for the return value. + + Parameters: ~ + {buffer} The buffer handle + {ns_id} a identifier returned previously with + nvim_create_namespace + {id} The extmark's id or 0 to create a new mark. + {row} The row to set the extmark to. + {col} The column to set the extmark to. + {opts} Optional parameters. Currently not used. + + Return: ~ + the id of the extmark. + +nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* + Remove an extmark + + Parameters: ~ + {buffer} The buffer handle + {ns_id} a identifier returned previously with + nvim_create_namespace + {id} The extmarks's id + + Return: ~ + true on success, false if the extmark was not found. + *nvim_buf_add_highlight()* nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, {col_start}, {col_end}) |