diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 167 |
1 files changed, 94 insertions, 73 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 07c45c9298..df345e4981 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -134,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 +indices, 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 @@ -436,36 +444,76 @@ 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. +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| + +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 + 0 1 2 3 4 5 character positions (0-based) + 0 1 2 3 4 5 6 extmark positions (0-based) + +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 z|b a r line (| = cursor) + 4 extmark (after typing "z") + +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: > + + f o o z b a r| line (| = cursor) + 7 extmark + + 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.. +< ^ 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, {}) - -We can get a mark by its id: > + let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {}) +< +We can get the 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): > +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 all surrounding text does NOT remove an extmark! To remove extmarks +use |nvim_buf_del_extmark()|. Deleting "x" in our example: > -Namespaces allow your plugin to manage only its own extmarks, ignoring those + 0 12345678 + 0 e|ample.. +< ^ extmark position +> + echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {}) + => [0, 1] +< + Note: Extmark "gravity" decides how it will shift after a text edit. + See |nvim_buf_set_extmark()| + +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 @@ -661,8 +709,7 @@ nvim_create_namespace({name}) *nvim_create_namespace()* 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_virtual_text()|. + see |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|. Namespaces can be named or anonymous. If `name` matches an existing namespace, the associated id is returned. If `name` @@ -780,10 +827,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) @@ -1104,7 +1150,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) intermediate mouse positions will be ignored. It should be used to implement real-time mouse input in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of - |nvim_input()| has the same limitiation. + |nvim_input()| has the same limitation. Attributes: ~ {fast} @@ -1183,7 +1229,7 @@ nvim_notify({msg}, {log_level}, {opts}) *nvim_notify()* Notify the user with a message Relays the call to vim.notify . By default forwards your - message in the echo area but can be overriden to trigger + message in the echo area but can be overridden to trigger desktop notifications. Parameters: ~ @@ -1197,7 +1243,7 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* By default (and currently the only option) the terminal will not be connected to an external process. Instead, input send on the channel will be echoed directly by the terminal. This - is useful to disply ANSI terminal sequences returned as part + is useful to display ANSI terminal sequences returned as part of a rpc message, or similar. Note: to directly initiate the terminal using the right size, @@ -1419,8 +1465,9 @@ nvim_parse_expression({expr}, {flags}, {highlight}) • "len": Amount of bytes successfully parsed. With flags equal to "" that should be equal to the length of expr - string. (“Sucessfully parsed” here means “participated - in AST creation”, not “till the first error”.) + string. (“Successfully parsed” here means + “participated in AST creation”, not “till the first + error”.) • "ast": AST, either nil or a dictionary with these keys: • "type": node type, one of the value names from @@ -1681,7 +1728,7 @@ nvim_set_decoration_provider({ns_id}, {opts}) Note: this function should not be called often. Rather, the callbacks themselves can be used to throttle unneeded callbacks. the `on_start` callback can return `false` to - disable the provider until the next redraw. Similarily, return + disable the provider until the next redraw. Similarly, return `false` in `on_win` will skip the `on_lines` calls for that window (but any extmarks set in `on_win` will still be used). A plugin managing multiple sources of decoration should @@ -1721,7 +1768,7 @@ nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* Parameters: ~ {ns_id} number of namespace for this highlight {name} highlight group name, like ErrorMsg - {val} highlight definiton map, like + {val} highlight definition map, like |nvim_get_hl_by_name|. in addition the following keys are also recognized: `default` : don't override existing definition, like `hi default` @@ -2072,7 +2119,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 +2129,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 +2170,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 @@ -2289,7 +2339,16 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) • hl_group : name of the highlight group used to highlight this mark. • virt_text : virtual text to link to this mark. - • virt_text_pos : positioning of virtual text. + A list of [text, highlight] tuples, each + representing a text chunk with specified + highlight. `highlight` element can either be a + a single highlight group, or an array of + multiple highlight groups that will be stacked + (highest priority last). A highlight group can + be supplied either as a string or as an + integer, the latter which can be obtained + using |nvim_get_hl_id_by_name|. + • virt_text_pos : position of virtual text. Possible values: • "eol": right after eol character (default) • "overlay": display over the specified @@ -2426,44 +2485,6 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* {name} Variable name {value} Variable value - *nvim_buf_set_virtual_text()* -nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks}, {opts}) - Set the virtual text (annotation) for a buffer line. - - By default (and currently the only option) the text will be - placed after the buffer text. Virtual text will never cause - reflow, rather virtual text will be truncated at the end of - the screen line. The virtual text will begin one cell - (|lcs-eol| or space) after the ordinary text. - - Namespaces are used to support batch deletion/updating of - virtual text. To create a namespace, use - |nvim_create_namespace()|. Virtual text is cleared using - |nvim_buf_clear_namespace()|. The same `ns_id` can be used for - both virtual text and highlights added by - |nvim_buf_add_highlight()|, both can then be cleared with a - single call to |nvim_buf_clear_namespace()|. If the virtual - text never will be cleared by an API call, pass `ns_id = -1` . - - As a shorthand, `ns_id = 0` can be used to create a new - namespace for the virtual text, the allocated id is then - returned. - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace to use or 0 to create a namespace, or - -1 for a ungrouped annotation - {line} Line to annotate with virtual text - (zero-indexed) - {chunks} A list of [text, hl_group] arrays, each - representing a text chunk with specified - highlight. `hl_group` element can be omitted for - no highlight. - {opts} Optional parameters. Currently not used. - - Return: ~ - The ns_id that was used - ============================================================================== Window Functions *api-window* |