From 9ef16a1628722958b6e14fe9274006e50ed6682d Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 27 Oct 2019 15:05:59 -0700 Subject: doc: vim.fn, vim.call(), vim.api [ci skip] --- runtime/doc/api.txt | 75 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 48 insertions(+), 27 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 98dd330b48..d6e420c427 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -850,10 +850,10 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* {enter} Enter the window (make it the current window) {config} Map defining the window configuration. Keys: • `relative` : Sets the window layout to "floating", placed - at (row,col) coordinates relative to one of: + at (row,col) coordinates relative to: • "editor" The global editor grid • "win" Window given by the `win` field, or - current window by default. + current window. • "cursor" Cursor position in current window. • `win` : |window-ID| for relative="win". @@ -1476,45 +1476,66 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* - Activates buffer-update events on a channel, or as lua + Activates buffer-update events on a channel, or as Lua callbacks. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {send_buffer} Set to true if the initial notification - should contain the whole buffer. If so, the - first notification will be a - `nvim_buf_lines_event` . Otherwise, the - first notification will be a - `nvim_buf_changedtick_event` . Not used for - lua callbacks. + {send_buffer} True if the initial notification should + contain the whole buffer: first + notification will be `nvim_buf_lines_event` + . Else the first notification will be + `nvim_buf_changedtick_event` . Not for Lua + callbacks. {opts} Optional parameters. - • `on_lines` : lua callback received on - change. - • `on_changedtick` : lua callback received - on changedtick increment without text - change. - • `utf_sizes` : include UTF-32 and UTF-16 - size of the replaced region. See - |api-buffer-updates-lua| for more - information + • on_lines: Lua callback invoked on change. + Return `true` to detach. Args: + • buffer handle + • b:changedtick + • first line that changed (zero-indexed) + • last line that was changed + • last line in the updated range + • byte count of previous contents + • deleted_codepoints (if `utf_sizes` is + true) + • deleted_codeunits (if `utf_sizes` is + true) + + • on_changedtick: Lua callback invoked on + changedtick increment without text + change. Args: + • buffer handle + • b:changedtick + + • on_detach: Lua callback invoked on + detach. Args: + • buffer handle + + • utf_sizes: include UTF-32 and UTF-16 size + of the replaced region, as args to + `on_lines` . + + Return: ~ + False if attach failed (invalid parameter, or buffer isn't + loaded); otherwise True. TODO: LUA_API_NO_EVAL - Return: ~ - False when updates couldn't be enabled because the buffer - isn't loaded or `opts` contained an invalid key; otherwise - True. TODO: LUA_API_NO_EVAL + See also: ~ + |nvim_buf_detach()| + |api-buffer-updates-lua| nvim_buf_detach({buffer}) *nvim_buf_detach()* Deactivates buffer-update events on the channel. - For Lua callbacks see |api-lua-detach|. - Parameters: ~ {buffer} Buffer handle, or 0 for current buffer Return: ~ - False when updates couldn't be disabled because the buffer - isn't loaded; otherwise True. + False if detach failed (because the buffer isn't loaded); + otherwise True. + + See also: ~ + |nvim_buf_attach()| + |api-lua-detach| for detaching Lua callbacks *nvim_buf_get_lines()* nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) -- cgit From 1cb4674547828a315b7aef5b6c635726b3bc12e5 Mon Sep 17 00:00:00 2001 From: Marco Hinz Date: Sun, 10 Nov 2019 16:38:04 +0100 Subject: api: add nvim_buf_get_virtual_text() (#11354) This adds the missing partner function of nvim_buf_set_virtual_text(). --- runtime/doc/api.txt | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index d6e420c427..93440f307c 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1842,6 +1842,27 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) Return: ~ The ns_id that was used +nvim_buf_get_virtual_text({buffer}, {lnum}) *nvim_buf_get_virtual_text()* + Get the virtual text (annotation) for a buffer line. + + The virtual text is returned as list of lists, whereas the + inner lists have either one or two elements. The first element + is the actual text, the optional second element is the + highlight group. + + The format is exactly the same as given to + nvim_buf_set_virtual_text(). + + If there is no virtual text associated with the given line, an + empty list is returned. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {line} Line to get the virtual text from (zero-indexed) + + Return: ~ + List of virtual text chunks + nvim__buf_stats({buffer}) *nvim__buf_stats()* TODO: Documentation -- cgit From a9065a50518ef59351f9d0d32041a991a751653f Mon Sep 17 00:00:00 2001 From: timeyyy Date: Wed, 18 Jan 2017 13:20:07 +0100 Subject: nsmarks: initial commit --- runtime/doc/api.txt | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 93440f307c..d6b7938633 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -438,6 +438,36 @@ Example: create a float with scratch buffer: > call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') > +============================================================================== +Buffer 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, +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. + +`let g:mark_ns = nvim_create_namespace('myplugin')` +`let g:mark_id = nvim_buf_set_mark(0, :g:mark_ns, 0, 1, 3)` + +Note: the mark id was randomly generated because we used an inital value of 0 + +`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]] + +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. + +The namepsace ensures you only ever work with the extended marks you mean to. + +Calling set and unset of marks will not automatically prop a new undo. + + ============================================================================== Global Functions *api-global* @@ -1449,6 +1479,22 @@ 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* -- cgit From 18a8b702c0ce7a8bacd84f6c95e440ae23a3299e Mon Sep 17 00:00:00 2001 From: Björn Linse Date: Sat, 9 Nov 2019 12:41:50 +0100 Subject: extmark: review changes --- runtime/doc/api.txt | 130 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 100 insertions(+), 30 deletions(-) (limited to 'runtime/doc/api.txt') 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}) -- cgit From 54473e9a677b001b47b1fe528b6056e9feed0f60 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 10 Nov 2019 16:52:14 -0800 Subject: doc [ci skip] --- runtime/doc/api.txt | 49 +++++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 24 deletions(-) (limited to 'runtime/doc/api.txt') 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}) -- cgit From af53a0c0123338575dd59934449d7fe836835d1c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 17 Nov 2019 19:06:59 -0800 Subject: doc: Lua [ci skip] #11378 - Rework :help lua-commands - Rename if_lua.txt => lua.txt --- runtime/doc/api.txt | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 4ed0a6aba0..57a72e6173 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -462,7 +462,7 @@ We can get a mark by its id: > We can get all marks in a buffer for our namespace (or by a range): > - echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, -1) + 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 @@ -1516,6 +1516,13 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. + Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its + contents): > + events = {} + vim.api.nvim_buf_attach(0, false, { + on_lines=function(...) table.insert(events, {...}) end}) +< + Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {send_buffer} True if the initial notification should @@ -1804,21 +1811,22 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) 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: + marks in the buffer can be queried as: - all_marks = nvim_buf_get_extmarks(0, my_ns, 0, -1, -1) + all_marks = nvim_buf_get_extmarks(0, my_ns, 0, -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. + traversed backwards. This is mostly useful 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 + {start} One of: extmark id, (row, col) or 0, -1 for buffer ends - {upper} One of: extmark id, (row, col) or 0, -1 for + {end} 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 @@ -1845,7 +1853,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) {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. + {line} The row to set the extmark to. {col} The column to set the extmark to. {opts} Optional parameters. Currently not used. -- cgit From d5f14b8372b3c8d441187eea659156534cb4c9ba Mon Sep 17 00:00:00 2001 From: Dennis B Date: Fri, 22 Nov 2019 20:55:04 +1100 Subject: Clear 'cc' in nvim_open_win 'minimal' style #11361 (#11427) * Clear 'cc' in nvim_open_win 'minimal' style #11361 Add 'colorcolumn' to the list of options that should be cleared when creating a 'minimal'-style floating window. --- runtime/doc/api.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 57a72e6173..f97795b0ee 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -933,10 +933,11 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* 'number', 'relativenumber', 'cursorline', 'cursorcolumn', 'foldcolumn', 'spell' and 'list' options. 'signcolumn' is changed to - `auto` . The end-of-buffer region is hidden - by setting `eob` flag of 'fillchars' to a - space char, and clearing the |EndOfBuffer| - region in 'winhighlight'. + `auto` and 'colorcolumn' is cleared. The + end-of-buffer region is hidden by setting + `eob` flag of 'fillchars' to a space char, and + clearing the |EndOfBuffer| region in + 'winhighlight'. Return: ~ Window handle, or 0 on error -- cgit From fd5710ae9a3bcbc0f9cbb71de9e39253350ff09c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 25 Nov 2019 01:08:02 -0800 Subject: doc + extmarks tweaks #11421 - nvim_buf_get_extmarks: rename "amount" => "limit" - rename `set_extmark_index_from_obj` --- runtime/doc/api.txt | 119 +++++++++++++++++++++++++++++----------------------- 1 file changed, 66 insertions(+), 53 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index f97795b0ee..0d040c154b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -19,6 +19,7 @@ API Usage *api-rpc* *RPC* *rpc* *msgpack-rpc* RPC is the typical way to control Nvim programmatically. Nvim implements the MessagePack-RPC protocol: + https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md Many clients use the API: user interfaces (GUIs), remote plugins, scripts like @@ -935,8 +936,8 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* 'list' options. 'signcolumn' is changed to `auto` and 'colorcolumn' is cleared. The end-of-buffer region is hidden by setting - `eob` flag of 'fillchars' to a space char, and - clearing the |EndOfBuffer| region in + `eob` flag of 'fillchars' to a space char, + and clearing the |EndOfBuffer| region in 'winhighlight'. Return: ~ @@ -1022,7 +1023,7 @@ nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()* {type} Edit behavior: any |getregtype()| result, or: • "b" |blockwise-visual| mode (may include width, e.g. "b3") - • "c" |characterwise| mode + • "c" |charwise| mode • "l" |linewise| mode • "" guess by contents, see |setreg()| {after} Insert after cursor (like |p|), or before (like @@ -1797,81 +1798,93 @@ 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 + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} 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 queried as: + Gets extmarks in "traversal order" from a |charwise| region + defined by buffer positions (inclusive, 0-indexed + |api-indexing|). + + Region can be given as (row,col) tuples, or valid extmark ids + (whose positions define the bounds). 0 and -1 are understood + as (0,0) and (-1,-1) respectively, thus the following are + equivalent: +> + nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) + nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {}) +< - all_marks = nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) + If `end` is less than `start` , traversal works backwards. + (Useful with `limit` , to get the first marks prior to a given + position.) - If end is a lower position than start, then the range will be - traversed backwards. This is mostly useful with limited - amount, to be able to get the first marks prior to a given - position. + Example: +> + local a = vim.api + local pos = a.nvim_win_get_cursor(0) + local ns = a.nvim_create_namespace('my-plugin') + -- Create new extmark at line 1, column 1. + local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, 0, {}) + -- Create new extmark at line 3, column 1. + local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, 0, {}) + -- Get extmarks only from line 3. + local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) + -- Get all marks in this buffer + namespace. + local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {}) + print(vim.inspect(ms)) +< Parameters: ~ - {buffer} The buffer handle - {ns_id} An id returned previously from - nvim_create_namespace - {start} One of: extmark id, (row, col) or 0, -1 for - buffer ends - {end} 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 + {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) + {opts} Optional parameters. Keys: + • limit: Maximum number of marks to return Return: ~ - [[extmark_id, row, col], ...] + List of [extmark_id, row, col] tuples in "traversal + order". *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. + Creates or updates an extmark. - 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. + To create a new extmark, pass id=0. The extmark id will be + returned. 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. (Useful over RPC, to avoid + waiting 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. - {line} The row to set the extmark to. - {col} The column to set the extmark to. + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id, or 0 to create new + {line} Line number where to place the mark + {col} Column where to place the mark {opts} Optional parameters. Currently not used. Return: ~ - the id of the extmark. + Id of the created/updated extmark nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* - Remove an extmark + Removes an extmark. Parameters: ~ - {buffer} The buffer handle - {ns_id} a identifier returned previously with - nvim_create_namespace - {id} The extmarks's id + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id Return: ~ - true on success, false if the extmark was not found. + true if the extmark was found, else false *nvim_buf_add_highlight()* nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, @@ -1916,8 +1929,8 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, *nvim_buf_clear_namespace()* nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) - Clears namespaced objects, highlights and virtual text, from a - line range + Clears namespaced objects (highlights, extmarks, virtual text) + from a region. Lines are 0-indexed. |api-indexing| To clear the namespace in the entire buffer, specify line_start=0 and line_end=-1. -- cgit From c34130d13a842ae0c0c1724d05800a954547d327 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 1 Dec 2019 22:43:16 -0800 Subject: API: deprecate nvim_command_output --- runtime/doc/api.txt | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 0d040c154b..afb5630b50 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -479,6 +479,24 @@ created for extmark changes. ============================================================================== Global Functions *api-global* +nvim_exec({src}, {output}) *nvim_exec()* + Executes Vimscript (multiline block of Ex-commands), like + anonymous |:source|. + + Optionally returns (non-error, non-shell |:!|) output. + + On execution error: fails with VimL error, does not update + v:errmsg. + + Parameters: ~ + {src} Vimscript code + {output} Capture and return all (non-error, non-shell + |:!|) output + + See also: ~ + |execute()| + |nvim_command()| + nvim_command({command}) *nvim_command()* Executes an ex-command. @@ -488,6 +506,9 @@ nvim_command({command}) *nvim_command()* Parameters: ~ {command} Ex-command string + See also: ~ + |nvim_exec()| + nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* Gets a highlight definition by name. @@ -609,19 +630,9 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) replace_termcodes cpoptions -nvim_command_output({command}) *nvim_command_output()* - Executes an ex-command and returns its (non-error) output. - Shell |:!| output is not captured. - - On execution error: fails with VimL error, does not update - v:errmsg. - - Parameters: ~ - {command} Ex-command string - nvim_eval({expr}) *nvim_eval()* - Evaluates a VimL expression (:help expression). Dictionaries - and Lists are recursively expanded. + Evaluates a VimL |expression|. Dictionaries and Lists are + recursively expanded. On execution error: fails with VimL error, does not update v:errmsg. -- cgit From a3b6c2a3dc5576db45fe4e893cfb8482af591c92 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 2 Dec 2019 00:46:46 -0800 Subject: API: rename nvim_execute_lua => nvim_exec_lua - We already find ourselves renaming nvim_execute_lua in tests and scripts, which suggests "exec" is the verb we actually want. - Add "exec" verb to `:help dev-api`. --- runtime/doc/api.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index afb5630b50..d52a9a8409 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -483,7 +483,8 @@ nvim_exec({src}, {output}) *nvim_exec()* Executes Vimscript (multiline block of Ex-commands), like anonymous |:source|. - Optionally returns (non-error, non-shell |:!|) output. + Unlike |nvim_command()| this function supports heredocs, + script-scope (s:), etc. On execution error: fails with VimL error, does not update v:errmsg. @@ -493,6 +494,10 @@ nvim_exec({src}, {output}) *nvim_exec()* {output} Capture and return all (non-error, non-shell |:!|) output + Return: ~ + Output (non-error, non-shell |:!|) if `output` is true, + else empty string. + See also: ~ |execute()| |nvim_command()| @@ -643,7 +648,7 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object -nvim_execute_lua({code}, {args}) *nvim_execute_lua()* +nvim_exec_lua({code}, {args}) *nvim_exec_lua()* Execute Lua code. Parameters (if any) are available as `...` inside the chunk. The chunk can return a value. -- cgit