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 From b81547ce6d182e2a7518e5a2f80d1ee90c5cdb8f Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 24 Dec 2019 00:04:14 -0800 Subject: gen_vimdoc.py: better handling of inline (non-block) nodes --- runtime/doc/api.txt | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index d52a9a8409..aa69186cf0 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -540,6 +540,11 @@ nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* See also: ~ nvim_get_hl_by_name +nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* + Gets a highlight group by name + + similar to |hlID()|, but allocates a new ID if not present. + nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* Sends input-keys to Nvim, subject to various quirks controlled by `mode` flags. This is a blocking call, unlike @@ -903,7 +908,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* {buffer} Buffer to display, or 0 for current buffer {enter} Enter the window (make it the current window) {config} Map defining the window configuration. Keys: - • `relative` : Sets the window layout to "floating", placed + • `relative`: Sets the window layout to "floating", placed at (row,col) coordinates relative to: • "editor" The global editor grid • "win" Window given by the `win` field, or @@ -1504,6 +1509,13 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* TODO: Documentation +nvim__put_attr({id}, {c0}, {c1}) *nvim__put_attr()* + Set attrs in nvim__buf_set_lua_hl callbacks + + TODO(bfredl): This is rather pedestrian. The final interface + should probably be derived from a reformed bufhl/virttext + interface with full support for multi-line ranges etc + ============================================================================== Buffer Functions *api-buffer* @@ -1599,6 +1611,22 @@ nvim_buf_detach({buffer}) *nvim_buf_detach()* |nvim_buf_attach()| |api-lua-detach| for detaching Lua callbacks +nvim__buf_set_luahl({buffer}, {opts}) *nvim__buf_set_luahl()* + Unstabilized interface for defining syntax hl in lua. + + This is not yet safe for general use, lua callbacks will need + to be restricted, like textlock and probably other stuff. + + The API on_line/nvim__put_attr is quite raw and not intended + to be the final shape. Ideally this should operate on chunks + larger than a single line to reduce interpreter overhead, and + generate annotation objects (bufhl/virttext) on the fly but + using the same representation. + + *nvim__buf_redraw_range()* +nvim__buf_redraw_range({buffer}, {first}, {last}) + TODO: Documentation + *nvim_buf_get_lines()* nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Gets a line-range from the buffer. -- cgit From c24f8f46b45f097dbe0abf7e6ae686bc9bec5568 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 28 Dec 2019 03:27:25 -0800 Subject: gen_vimdoc.py: sort by name --- runtime/doc/api.txt | 2026 +++++++++++++++++++++++++-------------------------- 1 file changed, 1013 insertions(+), 1013 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index aa69186cf0..7d45330b66 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -479,193 +479,110 @@ created for extmark changes. ============================================================================== Global Functions *api-global* -nvim_exec({src}, {output}) *nvim_exec()* - Executes Vimscript (multiline block of Ex-commands), like - anonymous |:source|. - - Unlike |nvim_command()| this function supports heredocs, - script-scope (s:), etc. +nvim__id({obj}) *nvim__id()* + Returns object given as argument. - On execution error: fails with VimL error, does not update - v:errmsg. + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {src} Vimscript code - {output} Capture and return all (non-error, non-shell - |:!|) output + {obj} Object to return. Return: ~ - Output (non-error, non-shell |:!|) if `output` is true, - else empty string. - - See also: ~ - |execute()| - |nvim_command()| - -nvim_command({command}) *nvim_command()* - Executes an ex-command. - - On execution error: fails with VimL error, does not update - v:errmsg. - - Parameters: ~ - {command} Ex-command string + its argument. - See also: ~ - |nvim_exec()| +nvim__id_array({arr}) *nvim__id_array()* + Returns array given as argument. -nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* - Gets a highlight definition by name. + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {name} Highlight group name - {rgb} Export RGB colors + {arr} Array to return. Return: ~ - Highlight definition map + its argument. - See also: ~ - nvim_get_hl_by_id +nvim__id_dictionary({dct}) *nvim__id_dictionary()* + Returns dictionary given as argument. -nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* - Gets a highlight definition by id. |hlID()| + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {hl_id} Highlight id as returned by |hlID()| - {rgb} Export RGB colors + {dct} Dictionary to return. Return: ~ - Highlight definition map - - See also: ~ - nvim_get_hl_by_name - -nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* - Gets a highlight group by name - - similar to |hlID()|, but allocates a new ID if not present. + its argument. -nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* - Sends input-keys to Nvim, subject to various quirks controlled - by `mode` flags. This is a blocking call, unlike - |nvim_input()|. +nvim__id_float({flt}) *nvim__id_float()* + Returns floating-point value given as argument. - On execution error: does not fail, but updates v:errmsg. + This API function is used for testing. One should not rely on + its presence in plugins. Parameters: ~ - {keys} to be typed - {mode} behavior flags, see |feedkeys()| - {escape_csi} If true, escape K_SPECIAL/CSI bytes in - `keys` - - See also: ~ - feedkeys() - vim_strsave_escape_csi + {flt} Value to return. -nvim_input({keys}) *nvim_input()* - Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a - low-level input buffer and the call is non-blocking (input is - processed asynchronously by the eventloop). + Return: ~ + its argument. - On execution error: does not fail, but updates v:errmsg. +nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* + TODO: Documentation - Note: - |keycodes| like are translated, so "<" is special. To - input a literal "<", send . - Note: - For mouse events use |nvim_input_mouse()|. The pseudokey - form "" is deprecated since - |api-level| 6. +nvim__put_attr({id}, {c0}, {c1}) *nvim__put_attr()* + Set attrs in nvim__buf_set_lua_hl callbacks - Attributes: ~ - {fast} + TODO(bfredl): This is rather pedestrian. The final interface + should probably be derived from a reformed bufhl/virttext + interface with full support for multi-line ranges etc - Parameters: ~ - {keys} to be typed +nvim__stats() *nvim__stats()* + Gets internal stats. Return: ~ - Number of bytes actually written (can be fewer than - requested if the buffer becomes full). - - *nvim_input_mouse()* -nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) - Send mouse event from GUI. - - Non-blocking: does not wait on any result, but queues the - event to be processed soon by the event loop. - - Note: - Currently this doesn't support "scripting" multiple mouse - events by calling it multiple times in a loop: the - intermediate mouse positions will be ignored. It should be - used to implement real-time mouse input in a GUI. The - deprecated pseudokey form ("") of - |nvim_input()| has the same limitiation. - - Attributes: ~ - {fast} + Map of various internal stats. - Parameters: ~ - {button} Mouse button: one of "left", "right", - "middle", "wheel". - {action} For ordinary buttons, one of "press", "drag", - "release". For the wheel, one of "up", "down", - "left", "right". - {modifier} String of modifiers each represented by a - single char. The same specifiers are used as - for a key press, except that the "-" separator - is optional, so "C-A-", "c-a" and "CA" can all - be used to specify Ctrl+Alt+click. - {grid} Grid number if the client uses |ui-multigrid|, - else 0. - {row} Mouse row-position (zero-based, like redraw - events) - {col} Mouse column-position (zero-based, like redraw - events) +nvim_call_atomic({calls}) *nvim_call_atomic()* + Calls many API methods atomically. - *nvim_replace_termcodes()* -nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) - Replaces terminal codes and |keycodes| (, , ...) in a - string with the internal representation. + This has two main usages: + 1. To perform several requests from an async context + atomically, i.e. without interleaving redraws, RPC requests + from other clients, or user interactions (however API + methods may trigger autocommands or event processing which + have such side-effects, e.g. |:sleep| may wake timers). + 2. To minimize RPC overhead (roundtrips) of a sequence of many + requests. Parameters: ~ - {str} String to be converted. - {from_part} Legacy Vim parameter. Usually true. - {do_lt} Also translate . Ignored if `special` is - false. - {special} Replace |keycodes|, e.g. becomes a "\n" - char. + {calls} an array of calls, where each call is described + by an array with two elements: the request name, + and an array of arguments. - See also: ~ - replace_termcodes - cpoptions + Return: ~ + Array of two elements. The first is an array of return + values. The second is NIL if all calls succeeded. If a + call resulted in an error, it is a three-element array + with the zero-based index of the call which resulted in an + error, the error type and the error message. If an error + occurred, the values from all preceding calls will still + be returned. -nvim_eval({expr}) *nvim_eval()* - Evaluates a VimL |expression|. Dictionaries and Lists are - recursively expanded. +nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()* + Calls a VimL |Dictionary-function| with the given arguments. On execution error: fails with VimL error, does not update v:errmsg. Parameters: ~ - {expr} VimL expression string - - Return: ~ - Evaluation result or expanded object - -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. - - Only statements are executed. To evaluate an expression, - prefix it with `return` : return my_function(...) - - Parameters: ~ - {code} Lua code to execute - {args} Arguments to the code + {dict} Dictionary, or String evaluating to a VimL |self| + dict + {fn} Name of the function defined on the VimL dict + {args} Function arguments packed in an Array Return: ~ - Return value of Lua code if present or NIL. + Result of the function call nvim_call_function({fn}, {args}) *nvim_call_function()* Calls a VimL function with the given arguments. @@ -680,146 +597,237 @@ nvim_call_function({fn}, {args}) *nvim_call_function()* Return: ~ Result of the function call -nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()* - Calls a VimL |Dictionary-function| with the given arguments. +nvim_command({command}) *nvim_command()* + Executes an ex-command. On execution error: fails with VimL error, does not update v:errmsg. Parameters: ~ - {dict} Dictionary, or String evaluating to a VimL |self| - dict - {fn} Name of the function defined on the VimL dict - {args} Function arguments packed in an Array + {command} Ex-command string - Return: ~ - Result of the function call + See also: ~ + |nvim_exec()| -nvim_strwidth({text}) *nvim_strwidth()* - Calculates the number of display cells occupied by `text` . - counts as one cell. +nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* + Creates a new, empty, unnamed buffer. Parameters: ~ - {text} Some text + {listed} Sets 'buflisted' + {scratch} Creates a "throwaway" |scratch-buffer| for + temporary work (always 'nomodified') Return: ~ - Number of cells + Buffer handle, or 0 on error -nvim_list_runtime_paths() *nvim_list_runtime_paths()* - Gets the paths contained in 'runtimepath'. + See also: ~ + buf_open_scratch - Return: ~ - List of paths +nvim_create_namespace({name}) *nvim_create_namespace()* + Creates a new namespace, or gets an existing one. -nvim_set_current_dir({dir}) *nvim_set_current_dir()* - Changes the global working directory. + Namespaces are used for buffer highlights and virtual text, + see |nvim_buf_add_highlight()| and + |nvim_buf_set_virtual_text()|. - Parameters: ~ - {dir} Directory path + Namespaces can be named or anonymous. If `name` matches an + existing namespace, the associated id is returned. If `name` + is an empty string a new, anonymous namespace is created. -nvim_get_current_line() *nvim_get_current_line()* - Gets the current line. + Parameters: ~ + {name} Namespace name or empty string Return: ~ - Current line string - -nvim_set_current_line({line}) *nvim_set_current_line()* - Sets the current line. - - Parameters: ~ - {line} Line contents + Namespace id nvim_del_current_line() *nvim_del_current_line()* Deletes the current line. -nvim_get_var({name}) *nvim_get_var()* - Gets a global (g:) variable. +nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* + Unmaps a global |mapping| for the given mode. + + To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. + + See also: ~ + |nvim_set_keymap()| + +nvim_del_var({name}) *nvim_del_var()* + Removes a global (g:) variable. Parameters: ~ {name} Variable name - Return: ~ - Variable value - -nvim_set_var({name}, {value}) *nvim_set_var()* - Sets a global (g:) variable. +nvim_err_write({str}) *nvim_err_write()* + Writes a message to the Vim error buffer. Does not append + "\n", the message is buffered (won't display) until a linefeed + is written. Parameters: ~ - {name} Variable name - {value} Variable value + {str} Message -nvim_del_var({name}) *nvim_del_var()* - Removes a global (g:) variable. +nvim_err_writeln({str}) *nvim_err_writeln()* + Writes a message to the Vim error buffer. Appends "\n", so the + buffer is flushed (and displayed). Parameters: ~ - {name} Variable name + {str} Message -nvim_get_vvar({name}) *nvim_get_vvar()* - Gets a v: variable. + See also: ~ + nvim_err_write() + +nvim_eval({expr}) *nvim_eval()* + Evaluates a VimL |expression|. Dictionaries and Lists are + recursively expanded. + + On execution error: fails with VimL error, does not update + v:errmsg. Parameters: ~ - {name} Variable name + {expr} VimL expression string Return: ~ - Variable value + Evaluation result or expanded object -nvim_set_vvar({name}, {value}) *nvim_set_vvar()* - Sets a v: variable, if it is not readonly. +nvim_exec({src}, {output}) *nvim_exec()* + Executes Vimscript (multiline block of Ex-commands), like + anonymous |:source|. - Parameters: ~ - {name} Variable name - {value} Variable value + Unlike |nvim_command()| this function supports heredocs, + script-scope (s:), etc. -nvim_get_option({name}) *nvim_get_option()* - Gets an option value string. + On execution error: fails with VimL error, does not update + v:errmsg. Parameters: ~ - {name} Option name + {src} Vimscript code + {output} Capture and return all (non-error, non-shell + |:!|) output Return: ~ - Option value (global) + Output (non-error, non-shell |:!|) if `output` is true, + else empty string. -nvim_set_option({name}, {value}) *nvim_set_option()* - Sets an option value. + See also: ~ + |execute()| + |nvim_command()| + +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. + + Only statements are executed. To evaluate an expression, + prefix it with `return` : return my_function(...) Parameters: ~ - {name} Option name - {value} New option value + {code} Lua code to execute + {args} Arguments to the code -nvim_out_write({str}) *nvim_out_write()* - Writes a message to the Vim output buffer. Does not append - "\n", the message is buffered (won't display) until a linefeed - is written. + Return: ~ + Return value of Lua code if present or NIL. + +nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* + Sends input-keys to Nvim, subject to various quirks controlled + by `mode` flags. This is a blocking call, unlike + |nvim_input()|. + + On execution error: does not fail, but updates v:errmsg. Parameters: ~ - {str} Message + {keys} to be typed + {mode} behavior flags, see |feedkeys()| + {escape_csi} If true, escape K_SPECIAL/CSI bytes in + `keys` -nvim_err_write({str}) *nvim_err_write()* - Writes a message to the Vim error buffer. Does not append - "\n", the message is buffered (won't display) until a linefeed - is written. + See also: ~ + feedkeys() + vim_strsave_escape_csi + +nvim_get_api_info() *nvim_get_api_info()* + Returns a 2-tuple (Array), where item 0 is the current channel + id and item 1 is the |api-metadata| map (Dictionary). + + Return: ~ + 2-tuple [{channel-id}, {api-metadata}] + + Attributes: ~ + {fast} + +nvim_get_chan_info({chan}) *nvim_get_chan_info()* + Get information about a channel. + + Return: ~ + Dictionary describing a channel, with these keys: + • "stream" the stream underlying the channel + • "stdio" stdin and stdout of this Nvim instance + • "stderr" stderr of this Nvim instance + • "socket" TCP/IP socket or named pipe + • "job" job with communication over its stdio + + • "mode" how data received on the channel is interpreted + • "bytes" send and receive raw bytes + • "terminal" a |terminal| instance interprets ASCII + sequences + • "rpc" |RPC| communication on the channel is active + + • "pty" Name of pseudoterminal, if one is used (optional). + On a POSIX system, this will be a device path like + /dev/pts/1. Even if the name is unknown, the key will + still be present to indicate a pty is used. This is + currently the case when using winpty on windows. + • "buffer" buffer with connected |terminal| instance + (optional) + • "client" information about the client on the other end + of the RPC channel, if it has added it using + |nvim_set_client_info()|. (optional) + +nvim_get_color_by_name({name}) *nvim_get_color_by_name()* + Returns the 24-bit RGB value of a |nvim_get_color_map()| color + name or "#rrggbb" hexadecimal string. + + Example: > + :echo nvim_get_color_by_name("Pink") + :echo nvim_get_color_by_name("#cbcbcb") +< Parameters: ~ - {str} Message + {name} Color name or "#rrggbb" string -nvim_err_writeln({str}) *nvim_err_writeln()* - Writes a message to the Vim error buffer. Appends "\n", so the - buffer is flushed (and displayed). + Return: ~ + 24-bit RGB value, or -1 for invalid argument. + +nvim_get_color_map() *nvim_get_color_map()* + Returns a map of color names and RGB values. + + Keys are color names (e.g. "Aqua") and values are 24-bit RGB + color values (e.g. 65535). + + Return: ~ + Map of color names and RGB values. + +nvim_get_commands({opts}) *nvim_get_commands()* + Gets a map of global (non-buffer-local) Ex commands. + + Currently only |user-commands| are supported, not builtin Ex + commands. Parameters: ~ - {str} Message + {opts} Optional parameters. Currently only supports + {"builtin":false} - See also: ~ - nvim_err_write() + Return: ~ + Map of maps describing commands. -nvim_list_bufs() *nvim_list_bufs()* - Gets the current list of buffer handles +nvim_get_context({opts}) *nvim_get_context()* + Gets a map of the current editor state. - Includes unlisted (unloaded/deleted) buffers, like `:ls!` . - Use |nvim_buf_is_loaded()| to check if a buffer is loaded. + Parameters: ~ + {opts} Optional parameters. + • types: List of |context-types| ("regs", "jumps", + "bufs", "gvars", …) to gather, or empty for + "all". Return: ~ - List of buffer handles + map of global |context|. nvim_get_current_buf() *nvim_get_current_buf()* Gets the current buffer. @@ -827,17 +835,17 @@ nvim_get_current_buf() *nvim_get_current_buf()* Return: ~ Buffer handle -nvim_set_current_buf({buffer}) *nvim_set_current_buf()* - Sets the current buffer. +nvim_get_current_line() *nvim_get_current_line()* + Gets the current line. - Parameters: ~ - {buffer} Buffer handle + Return: ~ + Current line string -nvim_list_wins() *nvim_list_wins()* - Gets the current list of window handles. +nvim_get_current_tabpage() *nvim_get_current_tabpage()* + Gets the current tabpage. Return: ~ - List of window handles + Tabpage handle nvim_get_current_win() *nvim_get_current_win()* Gets the current window. @@ -845,37 +853,227 @@ nvim_get_current_win() *nvim_get_current_win()* Return: ~ Window handle -nvim_set_current_win({window}) *nvim_set_current_win()* - Sets the current window. +nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* + Gets a highlight definition by id. |hlID()| Parameters: ~ - {window} Window handle + {hl_id} Highlight id as returned by |hlID()| + {rgb} Export RGB colors -nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* - Creates a new, empty, unnamed buffer. + Return: ~ + Highlight definition map + + See also: ~ + nvim_get_hl_by_name + +nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* + Gets a highlight definition by name. Parameters: ~ - {listed} Sets 'buflisted' - {scratch} Creates a "throwaway" |scratch-buffer| for - temporary work (always 'nomodified') + {name} Highlight group name + {rgb} Export RGB colors Return: ~ - Buffer handle, or 0 on error + Highlight definition map See also: ~ - buf_open_scratch + nvim_get_hl_by_id -nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* - Open a new window. +nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* + Gets a highlight group by name - Currently this is used to open floating and external windows. - Floats are windows that are drawn above the split layout, at - some anchor position in some other window. Floats can be drawn - internally or by external GUI with the |ui-multigrid| - extension. External windows are only supported with multigrid - GUIs, and are displayed as separate top-level windows. + similar to |hlID()|, but allocates a new ID if not present. - For a general overview of floats, see |api-floatwin|. +nvim_get_keymap({mode}) *nvim_get_keymap()* + Gets a list of global (non-buffer-local) |mapping| + definitions. + + Parameters: ~ + {mode} Mode short-name ("n", "i", "v", ...) + + Return: ~ + Array of maparg()-like dictionaries describing mappings. + The "buffer" key is always zero. + +nvim_get_mode() *nvim_get_mode()* + Gets the current mode. |mode()| "blocking" is true if Nvim is + waiting for input. + + Return: ~ + Dictionary { "mode": String, "blocking": Boolean } + + Attributes: ~ + {fast} + +nvim_get_namespaces() *nvim_get_namespaces()* + Gets existing, non-anonymous namespaces. + + Return: ~ + dict that maps from names to namespace ids. + +nvim_get_option({name}) *nvim_get_option()* + Gets an option value string. + + Parameters: ~ + {name} Option name + + Return: ~ + Option value (global) + +nvim_get_proc({pid}) *nvim_get_proc()* + Gets info describing process `pid` . + + Return: ~ + Map of process properties, or NIL if process not found. + +nvim_get_proc_children({pid}) *nvim_get_proc_children()* + Gets the immediate children of process `pid` . + + Return: ~ + Array of child process ids, empty if process not found. + +nvim_get_var({name}) *nvim_get_var()* + Gets a global (g:) variable. + + Parameters: ~ + {name} Variable name + + Return: ~ + Variable value + +nvim_get_vvar({name}) *nvim_get_vvar()* + Gets a v: variable. + + Parameters: ~ + {name} Variable name + + Return: ~ + Variable value + +nvim_input({keys}) *nvim_input()* + Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a + low-level input buffer and the call is non-blocking (input is + processed asynchronously by the eventloop). + + On execution error: does not fail, but updates v:errmsg. + + Note: + |keycodes| like are translated, so "<" is special. To + input a literal "<", send . + Note: + For mouse events use |nvim_input_mouse()|. The pseudokey + form "" is deprecated since + |api-level| 6. + + Attributes: ~ + {fast} + + Parameters: ~ + {keys} to be typed + + Return: ~ + Number of bytes actually written (can be fewer than + requested if the buffer becomes full). + + *nvim_input_mouse()* +nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) + Send mouse event from GUI. + + Non-blocking: does not wait on any result, but queues the + event to be processed soon by the event loop. + + Note: + Currently this doesn't support "scripting" multiple mouse + events by calling it multiple times in a loop: the + intermediate mouse positions will be ignored. It should be + used to implement real-time mouse input in a GUI. The + deprecated pseudokey form ("") of + |nvim_input()| has the same limitiation. + + Attributes: ~ + {fast} + + Parameters: ~ + {button} Mouse button: one of "left", "right", + "middle", "wheel". + {action} For ordinary buttons, one of "press", "drag", + "release". For the wheel, one of "up", "down", + "left", "right". + {modifier} String of modifiers each represented by a + single char. The same specifiers are used as + for a key press, except that the "-" separator + is optional, so "C-A-", "c-a" and "CA" can all + be used to specify Ctrl+Alt+click. + {grid} Grid number if the client uses |ui-multigrid|, + else 0. + {row} Mouse row-position (zero-based, like redraw + events) + {col} Mouse column-position (zero-based, like redraw + events) + +nvim_list_bufs() *nvim_list_bufs()* + Gets the current list of buffer handles + + Includes unlisted (unloaded/deleted) buffers, like `:ls!` . + Use |nvim_buf_is_loaded()| to check if a buffer is loaded. + + Return: ~ + List of buffer handles + +nvim_list_chans() *nvim_list_chans()* + Get information about all open channels. + + Return: ~ + Array of Dictionaries, each describing a channel with the + format specified at |nvim_get_chan_info()|. + +nvim_list_runtime_paths() *nvim_list_runtime_paths()* + Gets the paths contained in 'runtimepath'. + + Return: ~ + List of paths + +nvim_list_tabpages() *nvim_list_tabpages()* + Gets the current list of tabpage handles. + + Return: ~ + List of tabpage handles + +nvim_list_uis() *nvim_list_uis()* + Gets a list of dictionaries representing attached UIs. + + Return: ~ + Array of UI dictionaries, each with these keys: + • "height" Requested height of the UI + • "width" Requested width of the UI + • "rgb" true if the UI uses RGB colors (false implies + |cterm-colors|) + • "ext_..." Requested UI extensions, see |ui-option| + • "chan" Channel id of remote UI (not present for TUI) + +nvim_list_wins() *nvim_list_wins()* + Gets the current list of window handles. + + Return: ~ + List of window handles + +nvim_load_context({dict}) *nvim_load_context()* + Sets the current editor state from the given |context| map. + + Parameters: ~ + {dict} |Context| map. + +nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* + Open a new window. + + Currently this is used to open floating and external windows. + Floats are windows that are drawn above the split layout, at + some anchor position in some other window. Floats can be drawn + internally or by external GUI with the |ui-multigrid| + extension. External windows are only supported with multigrid + GUIs, and are displayed as separate top-level windows. + + For a general overview of floats, see |api-floatwin|. Exactly one of `external` and `relative` must be specified. The `width` and `height` of the new window must be specified. @@ -916,7 +1114,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* • "cursor" Cursor position in current window. • `win` : |window-ID| for relative="win". - • `anchor` : Decides which corner of the float to place + • `anchor`: Decides which corner of the float to place at (row,col): • "NW" northwest (default) • "NE" northeast @@ -946,7 +1144,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* an external top-level window. Currently accepts no other positioning configuration together with this. - • `style` : Configure the appearance of the window. + • `style`: Configure the appearance of the window. Currently only takes one non-empty value: • "minimal" Nvim will display the window with many UI options disabled. This is useful @@ -964,46 +1162,110 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* Return: ~ Window handle, or 0 on error -nvim_list_tabpages() *nvim_list_tabpages()* - Gets the current list of tabpage handles. - - Return: ~ - List of tabpage handles - -nvim_get_current_tabpage() *nvim_get_current_tabpage()* - Gets the current tabpage. - - Return: ~ - Tabpage handle - -nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* - Sets the current tabpage. +nvim_out_write({str}) *nvim_out_write()* + Writes a message to the Vim output buffer. Does not append + "\n", the message is buffered (won't display) until a linefeed + is written. Parameters: ~ - {tabpage} Tabpage handle - -nvim_create_namespace({name}) *nvim_create_namespace()* - Creates a new namespace, or gets an existing one. + {str} Message - Namespaces are used for buffer highlights and virtual text, - see |nvim_buf_add_highlight()| and - |nvim_buf_set_virtual_text()|. + *nvim_parse_expression()* +nvim_parse_expression({expr}, {flags}, {highlight}) + Parse a VimL expression. - Namespaces can be named or anonymous. If `name` matches an - existing namespace, the associated id is returned. If `name` - is an empty string a new, anonymous namespace is created. + Attributes: ~ + {fast} Parameters: ~ - {name} Namespace name or empty string + {expr} Expression to parse. Always treated as a + single line. + {flags} Flags: + • "m" if multiple expressions in a row are + allowed (only the first one will be + parsed), + • "E" if EOC tokens are not allowed + (determines whether they will stop parsing + process or be recognized as an + operator/space, though also yielding an + error). + • "l" when needing to start parsing with + lvalues for ":let" or ":for". Common flag + sets: + • "m" to parse like for ":echo". + • "E" to parse like for "=". + • empty string for ":call". + • "lm" to parse for ":let". + {highlight} If true, return value will also include + "highlight" key containing array of 4-tuples + (arrays) (Integer, Integer, Integer, String), + where first three numbers define the + highlighted region and represent line, + starting column and ending column (latter + exclusive: one should highlight region + [start_col, end_col)). Return: ~ - Namespace id -nvim_get_namespaces() *nvim_get_namespaces()* - Gets existing, non-anonymous namespaces. - - Return: ~ - dict that maps from names to namespace ids. + • AST: top-level dictionary with these keys: + • "error": Dictionary with error, present only if parser + saw some error. Contains the following keys: + • "message": String, error message in printf format, + translated. Must contain exactly one "%.*s". + • "arg": String, error message argument. + + • "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”.) + • "ast": AST, either nil or a dictionary with these + keys: + • "type": node type, one of the value names from + ExprASTNodeType stringified without "kExprNode" + prefix. + • "start": a pair [line, column] describing where node + is "started" where "line" is always 0 (will not be 0 + if you will be using nvim_parse_viml() on e.g. + ":let", but that is not present yet). Both elements + are Integers. + • "len": “length” of the node. This and "start" are + there for debugging purposes primary (debugging + parser and providing debug information). + • "children": a list of nodes described in top/"ast". + There always is zero, one or two children, key will + not be present if node has no children. Maximum + number of children may be found in node_maxchildren + array. + + • Local values (present only for certain nodes): + • "scope": a single Integer, specifies scope for + "Option" and "PlainIdentifier" nodes. For "Option" it + is one of ExprOptScope values, for "PlainIdentifier" + it is one of ExprVarScope values. + • "ident": identifier (without scope, if any), present + for "Option", "PlainIdentifier", "PlainKey" and + "Environment" nodes. + • "name": Integer, register name (one character) or -1. + Only present for "Register" nodes. + • "cmp_type": String, comparison type, one of the value + names from ExprComparisonType, stringified without + "kExprCmp" prefix. Only present for "Comparison" + nodes. + • "ccs_strategy": String, case comparison strategy, one + of the value names from ExprCaseCompareStrategy, + stringified without "kCCStrategy" prefix. Only present + for "Comparison" nodes. + • "augmentation": String, augmentation type for + "Assignment" nodes. Is either an empty string, "Add", + "Subtract" or "Concat" for "=", "+=", "-=" or ".=" + respectively. + • "invert": Boolean, true if result of comparison needs + to be inverted. Only present for "Comparison" nodes. + • "ivalue": Integer, integer value for "Integer" nodes. + • "fvalue": Float, floating-point value for "Float" + nodes. + • "svalue": String, value for "SingleQuotedString" and + "DoubleQuotedString" nodes. nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* Pastes at cursor, in any mode. @@ -1051,139 +1313,42 @@ nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()* |P|). {follow} Place cursor at end of inserted text. -nvim_subscribe({event}) *nvim_subscribe()* - Subscribes to event broadcasts. - - Parameters: ~ - {event} Event type string - -nvim_unsubscribe({event}) *nvim_unsubscribe()* - Unsubscribes to event broadcasts. - - Parameters: ~ - {event} Event type string - -nvim_get_color_by_name({name}) *nvim_get_color_by_name()* - Returns the 24-bit RGB value of a |nvim_get_color_map()| color - name or "#rrggbb" hexadecimal string. - - Example: > - :echo nvim_get_color_by_name("Pink") - :echo nvim_get_color_by_name("#cbcbcb") -< - - Parameters: ~ - {name} Color name or "#rrggbb" string - - Return: ~ - 24-bit RGB value, or -1 for invalid argument. - -nvim_get_color_map() *nvim_get_color_map()* - Returns a map of color names and RGB values. - - Keys are color names (e.g. "Aqua") and values are 24-bit RGB - color values (e.g. 65535). - - Return: ~ - Map of color names and RGB values. - -nvim_get_context({opts}) *nvim_get_context()* - Gets a map of the current editor state. - - Parameters: ~ - {opts} Optional parameters. - • types: List of |context-types| ("regs", "jumps", - "bufs", "gvars", …) to gather, or empty for - "all". - - Return: ~ - map of global |context|. - -nvim_load_context({dict}) *nvim_load_context()* - Sets the current editor state from the given |context| map. - - Parameters: ~ - {dict} |Context| map. - -nvim_get_mode() *nvim_get_mode()* - Gets the current mode. |mode()| "blocking" is true if Nvim is - waiting for input. - - Return: ~ - Dictionary { "mode": String, "blocking": Boolean } - - Attributes: ~ - {fast} - -nvim_get_keymap({mode}) *nvim_get_keymap()* - Gets a list of global (non-buffer-local) |mapping| - definitions. - - Parameters: ~ - {mode} Mode short-name ("n", "i", "v", ...) - - Return: ~ - Array of maparg()-like dictionaries describing mappings. - The "buffer" key is always zero. - -nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* - Sets a global |mapping| for the given mode. - - To set a buffer-local mapping, use |nvim_buf_set_keymap()|. - - Unlike |:map|, leading/trailing whitespace is accepted as part - of the {lhs} or {rhs}. Empty {rhs} is ||. |keycodes| are - replaced as usual. - - Example: > - call nvim_set_keymap('n', ' ', '', {'nowait': v:true}) -< - - is equivalent to: > - nmap -< + *nvim_replace_termcodes()* +nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) + Replaces terminal codes and |keycodes| (, , ...) in a + string with the internal representation. Parameters: ~ - {mode} Mode short-name (map command prefix: "n", "i", - "v", "x", …) or "!" for |:map!|, or empty string - for |:map|. - {lhs} Left-hand-side |{lhs}| of the mapping. - {rhs} Right-hand-side |{rhs}| of the mapping. - {opts} Optional parameters map. Accepts all - |:map-arguments| as keys excluding || but - including |noremap|. Values are Booleans. Unknown - key is an error. - -nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* - Unmaps a global |mapping| for the given mode. - - To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. + {str} String to be converted. + {from_part} Legacy Vim parameter. Usually true. + {do_lt} Also translate . Ignored if `special` is + false. + {special} Replace |keycodes|, e.g. becomes a "\n" + char. See also: ~ - |nvim_set_keymap()| + replace_termcodes + cpoptions -nvim_get_commands({opts}) *nvim_get_commands()* - Gets a map of global (non-buffer-local) Ex commands. + *nvim_select_popupmenu_item()* +nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) + Selects an item in the completion popupmenu. - Currently only |user-commands| are supported, not builtin Ex - commands. + If |ins-completion| is not active this API call is silently + ignored. Useful for an external UI using |ui-popupmenu| to + control the popupmenu with the mouse. Can also be used in a + mapping; use |:map-cmd| to ensure the mapping doesn't + end completion mode. Parameters: ~ - {opts} Optional parameters. Currently only supports - {"builtin":false} - - Return: ~ - Map of maps describing commands. - -nvim_get_api_info() *nvim_get_api_info()* - Returns a 2-tuple (Array), where item 0 is the current channel - id and item 1 is the |api-metadata| map (Dictionary). - - Return: ~ - 2-tuple [{channel-id}, {api-metadata}] - - Attributes: ~ - {fast} + {item} Index (zero-based) of the item to select. Value + of -1 selects nothing and restores the original + text. + {insert} Whether the selection should be inserted in the + buffer. + {finish} Finish the completion and dismiss the popupmenu. + Implies `insert` . + {opts} Optional parameters. Reserved for future use. *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, @@ -1250,271 +1415,106 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, small logo or icon. .png or .svg format is preferred. -nvim_get_chan_info({chan}) *nvim_get_chan_info()* - Get information about a channel. - - Return: ~ - Dictionary describing a channel, with these keys: - • "stream" the stream underlying the channel - • "stdio" stdin and stdout of this Nvim instance - • "stderr" stderr of this Nvim instance - • "socket" TCP/IP socket or named pipe - • "job" job with communication over its stdio - - • "mode" how data received on the channel is interpreted - • "bytes" send and receive raw bytes - • "terminal" a |terminal| instance interprets ASCII - sequences - • "rpc" |RPC| communication on the channel is active - - • "pty" Name of pseudoterminal, if one is used (optional). - On a POSIX system, this will be a device path like - /dev/pts/1. Even if the name is unknown, the key will - still be present to indicate a pty is used. This is - currently the case when using winpty on windows. - • "buffer" buffer with connected |terminal| instance - (optional) - • "client" information about the client on the other end - of the RPC channel, if it has added it using - |nvim_set_client_info()|. (optional) +nvim_set_current_buf({buffer}) *nvim_set_current_buf()* + Sets the current buffer. -nvim_list_chans() *nvim_list_chans()* - Get information about all open channels. + Parameters: ~ + {buffer} Buffer handle - Return: ~ - Array of Dictionaries, each describing a channel with the - format specified at |nvim_get_chan_info()|. +nvim_set_current_dir({dir}) *nvim_set_current_dir()* + Changes the global working directory. -nvim_call_atomic({calls}) *nvim_call_atomic()* - Calls many API methods atomically. + Parameters: ~ + {dir} Directory path - This has two main usages: - 1. To perform several requests from an async context - atomically, i.e. without interleaving redraws, RPC requests - from other clients, or user interactions (however API - methods may trigger autocommands or event processing which - have such side-effects, e.g. |:sleep| may wake timers). - 2. To minimize RPC overhead (roundtrips) of a sequence of many - requests. +nvim_set_current_line({line}) *nvim_set_current_line()* + Sets the current line. Parameters: ~ - {calls} an array of calls, where each call is described - by an array with two elements: the request name, - and an array of arguments. + {line} Line contents - Return: ~ - Array of two elements. The first is an array of return - values. The second is NIL if all calls succeeded. If a - call resulted in an error, it is a three-element array - with the zero-based index of the call which resulted in an - error, the error type and the error message. If an error - occurred, the values from all preceding calls will still - be returned. +nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* + Sets the current tabpage. - *nvim_parse_expression()* -nvim_parse_expression({expr}, {flags}, {highlight}) - Parse a VimL expression. + Parameters: ~ + {tabpage} Tabpage handle - Attributes: ~ - {fast} +nvim_set_current_win({window}) *nvim_set_current_win()* + Sets the current window. Parameters: ~ - {expr} Expression to parse. Always treated as a - single line. - {flags} Flags: - • "m" if multiple expressions in a row are - allowed (only the first one will be - parsed), - • "E" if EOC tokens are not allowed - (determines whether they will stop parsing - process or be recognized as an - operator/space, though also yielding an - error). - • "l" when needing to start parsing with - lvalues for ":let" or ":for". Common flag - sets: - • "m" to parse like for ":echo". - • "E" to parse like for "=". - • empty string for ":call". - • "lm" to parse for ":let". - {highlight} If true, return value will also include - "highlight" key containing array of 4-tuples - (arrays) (Integer, Integer, Integer, String), - where first three numbers define the - highlighted region and represent line, - starting column and ending column (latter - exclusive: one should highlight region - [start_col, end_col)). - - Return: ~ + {window} Window handle - • AST: top-level dictionary with these keys: - • "error": Dictionary with error, present only if parser - saw some error. Contains the following keys: - • "message": String, error message in printf format, - translated. Must contain exactly one "%.*s". - • "arg": String, error message argument. +nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* + Sets a global |mapping| for the given mode. - • "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”.) - • "ast": AST, either nil or a dictionary with these - keys: - • "type": node type, one of the value names from - ExprASTNodeType stringified without "kExprNode" - prefix. - • "start": a pair [line, column] describing where node - is "started" where "line" is always 0 (will not be 0 - if you will be using nvim_parse_viml() on e.g. - ":let", but that is not present yet). Both elements - are Integers. - • "len": “length” of the node. This and "start" are - there for debugging purposes primary (debugging - parser and providing debug information). - • "children": a list of nodes described in top/"ast". - There always is zero, one or two children, key will - not be present if node has no children. Maximum - number of children may be found in node_maxchildren - array. + To set a buffer-local mapping, use |nvim_buf_set_keymap()|. - • Local values (present only for certain nodes): - • "scope": a single Integer, specifies scope for - "Option" and "PlainIdentifier" nodes. For "Option" it - is one of ExprOptScope values, for "PlainIdentifier" - it is one of ExprVarScope values. - • "ident": identifier (without scope, if any), present - for "Option", "PlainIdentifier", "PlainKey" and - "Environment" nodes. - • "name": Integer, register name (one character) or -1. - Only present for "Register" nodes. - • "cmp_type": String, comparison type, one of the value - names from ExprComparisonType, stringified without - "kExprCmp" prefix. Only present for "Comparison" - nodes. - • "ccs_strategy": String, case comparison strategy, one - of the value names from ExprCaseCompareStrategy, - stringified without "kCCStrategy" prefix. Only present - for "Comparison" nodes. - • "augmentation": String, augmentation type for - "Assignment" nodes. Is either an empty string, "Add", - "Subtract" or "Concat" for "=", "+=", "-=" or ".=" - respectively. - • "invert": Boolean, true if result of comparison needs - to be inverted. Only present for "Comparison" nodes. - • "ivalue": Integer, integer value for "Integer" nodes. - • "fvalue": Float, floating-point value for "Float" - nodes. - • "svalue": String, value for "SingleQuotedString" and - "DoubleQuotedString" nodes. + Unlike |:map|, leading/trailing whitespace is accepted as part + of the {lhs} or {rhs}. Empty {rhs} is ||. |keycodes| are + replaced as usual. -nvim__id({obj}) *nvim__id()* - Returns object given as argument. + Example: > + call nvim_set_keymap('n', ' ', '', {'nowait': v:true}) +< - This API function is used for testing. One should not rely on - its presence in plugins. + is equivalent to: > + nmap +< Parameters: ~ - {obj} Object to return. - - Return: ~ - its argument. - -nvim__id_array({arr}) *nvim__id_array()* - Returns array given as argument. + {mode} Mode short-name (map command prefix: "n", "i", + "v", "x", …) or "!" for |:map!|, or empty string + for |:map|. + {lhs} Left-hand-side |{lhs}| of the mapping. + {rhs} Right-hand-side |{rhs}| of the mapping. + {opts} Optional parameters map. Accepts all + |:map-arguments| as keys excluding || but + including |noremap|. Values are Booleans. Unknown + key is an error. - This API function is used for testing. One should not rely on - its presence in plugins. +nvim_set_option({name}, {value}) *nvim_set_option()* + Sets an option value. Parameters: ~ - {arr} Array to return. - - Return: ~ - its argument. - -nvim__id_dictionary({dct}) *nvim__id_dictionary()* - Returns dictionary given as argument. + {name} Option name + {value} New option value - This API function is used for testing. One should not rely on - its presence in plugins. +nvim_set_var({name}, {value}) *nvim_set_var()* + Sets a global (g:) variable. Parameters: ~ - {dct} Dictionary to return. - - Return: ~ - its argument. - -nvim__id_float({flt}) *nvim__id_float()* - Returns floating-point value given as argument. + {name} Variable name + {value} Variable value - This API function is used for testing. One should not rely on - its presence in plugins. +nvim_set_vvar({name}, {value}) *nvim_set_vvar()* + Sets a v: variable, if it is not readonly. Parameters: ~ - {flt} Value to return. - - Return: ~ - its argument. - -nvim__stats() *nvim__stats()* - Gets internal stats. - - Return: ~ - Map of various internal stats. - -nvim_list_uis() *nvim_list_uis()* - Gets a list of dictionaries representing attached UIs. - - Return: ~ - Array of UI dictionaries, each with these keys: - • "height" Requested height of the UI - • "width" Requested width of the UI - • "rgb" true if the UI uses RGB colors (false implies - |cterm-colors|) - • "ext_..." Requested UI extensions, see |ui-option| - • "chan" Channel id of remote UI (not present for TUI) - -nvim_get_proc_children({pid}) *nvim_get_proc_children()* - Gets the immediate children of process `pid` . - - Return: ~ - Array of child process ids, empty if process not found. - -nvim_get_proc({pid}) *nvim_get_proc()* - Gets info describing process `pid` . - - Return: ~ - Map of process properties, or NIL if process not found. - - *nvim_select_popupmenu_item()* -nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) - Selects an item in the completion popupmenu. + {name} Variable name + {value} Variable value - If |ins-completion| is not active this API call is silently - ignored. Useful for an external UI using |ui-popupmenu| to - control the popupmenu with the mouse. Can also be used in a - mapping; use |:map-cmd| to ensure the mapping doesn't - end completion mode. +nvim_strwidth({text}) *nvim_strwidth()* + Calculates the number of display cells occupied by `text` . + counts as one cell. Parameters: ~ - {item} Index (zero-based) of the item to select. Value - of -1 selects nothing and restores the original - text. - {insert} Whether the selection should be inserted in the - buffer. - {finish} Finish the completion and dismiss the popupmenu. - Implies `insert` . - {opts} Optional parameters. Reserved for future use. + {text} Some text -nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* - TODO: Documentation + Return: ~ + Number of cells -nvim__put_attr({id}, {c0}, {c1}) *nvim__put_attr()* - Set attrs in nvim__buf_set_lua_hl callbacks +nvim_subscribe({event}) *nvim_subscribe()* + Subscribes to event broadcasts. - TODO(bfredl): This is rather pedestrian. The final interface - should probably be derived from a reformed bufhl/virttext - interface with full support for multi-line ranges etc + Parameters: ~ + {event} Event type string + +nvim_unsubscribe({event}) *nvim_unsubscribe()* + Unsubscribes to event broadcasts. + + Parameters: ~ + {event} Event type string ============================================================================== @@ -1533,14 +1533,65 @@ affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. -nvim_buf_line_count({buffer}) *nvim_buf_line_count()* - Gets the buffer line count + *nvim__buf_redraw_range()* +nvim__buf_redraw_range({buffer}, {first}, {last}) + TODO: Documentation + +nvim__buf_set_luahl({buffer}, {opts}) *nvim__buf_set_luahl()* + Unstabilized interface for defining syntax hl in lua. + + This is not yet safe for general use, lua callbacks will need + to be restricted, like textlock and probably other stuff. + + The API on_line/nvim__put_attr is quite raw and not intended + to be the final shape. Ideally this should operate on chunks + larger than a single line to reduce interpreter overhead, and + generate annotation objects (bufhl/virttext) on the fly but + using the same representation. + +nvim__buf_stats({buffer}) *nvim__buf_stats()* + TODO: Documentation + + *nvim_buf_add_highlight()* +nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, + {col_start}, {col_end}) + Adds a highlight to buffer. + + Useful for plugins that dynamically generate highlights to a + buffer (like a semantic highlighter or linter). The function + adds a single highlight to a buffer. Unlike |matchaddpos()| + highlights follow changes to line numbering (as lines are + inserted/removed above the highlighted line), like signs and + marks do. + + Namespaces are used for batch deletion/updating of a set of + highlights. To create a namespace, use |nvim_create_namespace| + which returns a namespace id. Pass it in to this function as + `ns_id` to add highlights to the namespace. All highlights in + the same namespace can then be cleared with single call to + |nvim_buf_clear_namespace|. If the highlight never will be + deleted by an API call, pass `ns_id = -1` . + + As a shorthand, `ns_id = 0` can be used to create a new + namespace for the highlight, the allocated id is then + returned. If `hl_group` is the empty string no highlight is + added, but a new `ns_id` is still returned. This is supported + for backwards compatibility, new code should use + |nvim_create_namespace| to create a new empty namespace. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + {buffer} Buffer handle, or 0 for current buffer + {ns_id} namespace to use or -1 for ungrouped + highlight + {hl_group} Name of the highlight group to use + {line} Line to highlight (zero-indexed) + {col_start} Start of (byte-indexed) column range to + highlight + {col_end} End of (byte-indexed) column range to + highlight, or -1 to highlight to end of line Return: ~ - Line count, or 0 for unloaded buffer. |api-buffer| + The ns_id that was used nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua @@ -1563,7 +1614,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* callbacks. {opts} Optional parameters. • on_lines: Lua callback invoked on change. - Return `true` to detach. Args: + Return`true`to detach. Args: • buffer handle • b:changedtick • first line that changed (zero-indexed) @@ -1597,119 +1648,142 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* |nvim_buf_detach()| |api-buffer-updates-lua| -nvim_buf_detach({buffer}) *nvim_buf_detach()* - Deactivates buffer-update events on the channel. + *nvim_buf_clear_namespace()* +nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) + 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. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace to clear, or -1 to clear all + namespaces. + {line_start} Start of range of lines to clear + {line_end} End of range of lines to clear (exclusive) + or -1 to clear to end of buffer. - Return: ~ - False if detach failed (because the buffer isn't loaded); - otherwise True. +nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* + Removes an extmark. - See also: ~ - |nvim_buf_attach()| - |api-lua-detach| for detaching Lua callbacks + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id -nvim__buf_set_luahl({buffer}, {opts}) *nvim__buf_set_luahl()* - Unstabilized interface for defining syntax hl in lua. + Return: ~ + true if the extmark was found, else false - This is not yet safe for general use, lua callbacks will need - to be restricted, like textlock and probably other stuff. +nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* + Unmaps a buffer-local |mapping| for the given mode. - The API on_line/nvim__put_attr is quite raw and not intended - to be the final shape. Ideally this should operate on chunks - larger than a single line to reduce interpreter overhead, and - generate annotation objects (bufhl/virttext) on the fly but - using the same representation. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer - *nvim__buf_redraw_range()* -nvim__buf_redraw_range({buffer}, {first}, {last}) - TODO: Documentation + See also: ~ + |nvim_del_keymap()| - *nvim_buf_get_lines()* -nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) - Gets a line-range from the buffer. +nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* + Removes a buffer-scoped (b:) variable - Indexing is zero-based, end-exclusive. Negative indices are - interpreted as length+1+index: -1 refers to the index past the - end. So to get the last element use start=-2 and end=-1. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Variable name - Out-of-bounds indices are clamped to the nearest valid value, - unless `strict_indexing` is set. +nvim_buf_detach({buffer}) *nvim_buf_detach()* + Deactivates buffer-update events on the channel. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start} First line index - {end} Last line index (exclusive) - {strict_indexing} Whether out-of-bounds should be an - error. + {buffer} Buffer handle, or 0 for current buffer Return: ~ - Array of lines, or empty array for unloaded buffer. - - *nvim_buf_set_lines()* -nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, - {replacement}) - Sets (replaces) a line-range in the buffer. - - Indexing is zero-based, end-exclusive. Negative indices are - interpreted as length+1+index: -1 refers to the index past the - end. So to change or delete the last element use start=-2 and - end=-1. + False if detach failed (because the buffer isn't loaded); + otherwise True. - To insert lines at a given index, set `start` and `end` to the - same index. To delete a range of lines, set `replacement` to - an empty array. + See also: ~ + |nvim_buf_attach()| + |api-lua-detach| for detaching Lua callbacks - Out-of-bounds indices are clamped to the nearest valid value, - unless `strict_indexing` is set. +nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* + Gets a changed tick of a buffer Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {start} First line index - {end} Last line index (exclusive) - {strict_indexing} Whether out-of-bounds should be an - error. - {replacement} Array of lines to use as replacement - -nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* - Returns the byte offset of a line (0-indexed). |api-indexing| + {buffer} Buffer handle, or 0 for current buffer - Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is - one byte. 'fileformat' and 'fileencoding' are ignored. The - line index just after the last line gives the total byte-count - of the buffer. A final EOL byte is counted if it would be - written, see 'eol'. + Return: ~ + `b:changedtick` value. - Unlike |line2byte()|, throws error for out-of-bounds indexing. - Returns -1 for unloaded buffer. +nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* + Gets a map of buffer-local |user-commands|. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {index} Line index + {opts} Optional parameters. Currently not used. Return: ~ - Integer byte offset, or -1 for unloaded buffer. + Map of maps describing commands. -nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* - Gets a buffer-scoped (b:) variable. + *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} Buffer handle, or 0 for current buffer - {name} Variable name + {ns_id} Namespace id from |nvim_create_namespace()| + {id} Extmark id Return: ~ - Variable value + (row, col) tuple or empty list () if extmark id was absent -nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* - Gets a changed tick of a buffer + *nvim_buf_get_extmarks()* +nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) + 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], {}) +< + + If `end` is less than `start` , traversal works backwards. + (Useful with `limit` , 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} 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: ~ - `b:changedtick` value. + List of [extmark_id, row, col] tuples in "traversal + order". nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Gets a list of buffer-local |mapping| definitions. @@ -1722,49 +1796,67 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Array of maparg()-like dictionaries describing mappings. The "buffer" key holds the associated buffer handle. - *nvim_buf_set_keymap()* -nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) - Sets a buffer-local |mapping| for the given mode. + *nvim_buf_get_lines()* +nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) + Gets a line-range from the buffer. + + Indexing is zero-based, end-exclusive. Negative indices are + interpreted as length+1+index: -1 refers to the index past the + end. So to get the last element use start=-2 and end=-1. + + Out-of-bounds indices are clamped to the nearest valid value, + unless `strict_indexing` is set. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer + {buffer} Buffer handle, or 0 for current buffer + {start} First line index + {end} Last line index (exclusive) + {strict_indexing} Whether out-of-bounds should be an + error. - See also: ~ - |nvim_set_keymap()| + Return: ~ + Array of lines, or empty array for unloaded buffer. -nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* - Unmaps a buffer-local |mapping| for the given mode. +nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* + Return a tuple (row,col) representing the position of the + named mark. + + Marks are (1,0)-indexed. |api-indexing| Parameters: ~ {buffer} Buffer handle, or 0 for current buffer + {name} Mark name - See also: ~ - |nvim_del_keymap()| + Return: ~ + (row, col) tuple -nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* - Gets a map of buffer-local |user-commands|. +nvim_buf_get_name({buffer}) *nvim_buf_get_name()* + Gets the full file name for the buffer Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {opts} Optional parameters. Currently not used. Return: ~ - Map of maps describing commands. + Buffer name -nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* - Sets a buffer-scoped (b:) variable +nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* + Returns the byte offset of a line (0-indexed). |api-indexing| - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Variable name - {value} Variable value + Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is + one byte. 'fileformat' and 'fileencoding' are ignored. The + line index just after the last line gives the total byte-count + of the buffer. A final EOL byte is counted if it would be + written, see 'eol'. -nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* - Removes a buffer-scoped (b:) variable + Unlike |line2byte()|, throws error for out-of-bounds indexing. + Returns -1 for unloaded buffer. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {name} Variable name + {index} Line index + + Return: ~ + Integer byte offset, or -1 for unloaded buffer. nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* Gets a buffer option value @@ -1776,30 +1868,36 @@ nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* Return: ~ Option value -nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* - Sets a buffer option value. Passing 'nil' as value deletes the - option (only works if there's a global fallback) +nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* + Gets a buffer-scoped (b:) variable. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {name} Option name - {value} Option value + {name} Variable name -nvim_buf_get_name({buffer}) *nvim_buf_get_name()* - Gets the full file name for the buffer + Return: ~ + Variable value - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer +nvim_buf_get_virtual_text({buffer}, {lnum}) *nvim_buf_get_virtual_text()* + Get the virtual text (annotation) for a buffer line. - Return: ~ - Buffer name + 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. -nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* - Sets the full file name for a buffer + 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 - {name} Buffer name + {line} Line to get the virtual text from (zero-indexed) + + Return: ~ + List of virtual text chunks nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* Checks if a buffer is valid and loaded. See |api-buffer| for @@ -1824,79 +1922,14 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* Return: ~ true if the buffer is valid, false otherwise. -nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* - Return a tuple (row,col) representing the position of the - named mark. - - Marks are (1,0)-indexed. |api-indexing| - - Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {name} Mark name - - 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} 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}) - 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], {}) -< - - If `end` is less than `start` , traversal works backwards. - (Useful with `limit` , 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)) -< +nvim_buf_line_count({buffer}) *nvim_buf_line_count()* + Gets the buffer line count 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) - {opts} Optional parameters. Keys: - • limit: Maximum number of marks to return Return: ~ - List of [extmark_id, row, col] tuples in "traversal - order". + Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_extmark()* nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) @@ -1919,73 +1952,64 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts}) Return: ~ Id of the created/updated extmark -nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* - Removes an extmark. + *nvim_buf_set_keymap()* +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) + Sets a buffer-local |mapping| for the given mode. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace id from |nvim_create_namespace()| - {id} Extmark id - Return: ~ - true if the extmark was found, else false + See also: ~ + |nvim_set_keymap()| - *nvim_buf_add_highlight()* -nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, - {col_start}, {col_end}) - Adds a highlight to buffer. + *nvim_buf_set_lines()* +nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, + {replacement}) + Sets (replaces) a line-range in the buffer. - Useful for plugins that dynamically generate highlights to a - buffer (like a semantic highlighter or linter). The function - adds a single highlight to a buffer. Unlike |matchaddpos()| - highlights follow changes to line numbering (as lines are - inserted/removed above the highlighted line), like signs and - marks do. + Indexing is zero-based, end-exclusive. Negative indices are + interpreted as length+1+index: -1 refers to the index past the + end. So to change or delete the last element use start=-2 and + end=-1. - Namespaces are used for batch deletion/updating of a set of - highlights. To create a namespace, use |nvim_create_namespace| - which returns a namespace id. Pass it in to this function as - `ns_id` to add highlights to the namespace. All highlights in - the same namespace can then be cleared with single call to - |nvim_buf_clear_namespace|. If the highlight never will be - deleted by an API call, pass `ns_id = -1` . + To insert lines at a given index, set `start` and `end` to the + same index. To delete a range of lines, set `replacement` to + an empty array. - As a shorthand, `ns_id = 0` can be used to create a new - namespace for the highlight, the allocated id is then - returned. If `hl_group` is the empty string no highlight is - added, but a new `ns_id` is still returned. This is supported - for backwards compatibility, new code should use - |nvim_create_namespace| to create a new empty namespace. + Out-of-bounds indices are clamped to the nearest valid value, + unless `strict_indexing` is set. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} namespace to use or -1 for ungrouped - highlight - {hl_group} Name of the highlight group to use - {line} Line to highlight (zero-indexed) - {col_start} Start of (byte-indexed) column range to - highlight - {col_end} End of (byte-indexed) column range to - highlight, or -1 to highlight to end of line + {buffer} Buffer handle, or 0 for current buffer + {start} First line index + {end} Last line index (exclusive) + {strict_indexing} Whether out-of-bounds should be an + error. + {replacement} Array of lines to use as replacement - Return: ~ - The ns_id that was used +nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* + Sets the full file name for a buffer - *nvim_buf_clear_namespace()* -nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) - Clears namespaced objects (highlights, extmarks, virtual text) - from a region. + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Buffer name - Lines are 0-indexed. |api-indexing| To clear the namespace in - the entire buffer, specify line_start=0 and line_end=-1. +nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* + Sets a buffer option value. Passing 'nil' as value deletes the + option (only works if there's a global fallback) + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {name} Option name + {value} Option value + +nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* + Sets a buffer-scoped (b:) variable Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {ns_id} Namespace to clear, or -1 to clear all - namespaces. - {line_start} Start of range of lines to clear - {line_end} End of range of lines to clear (exclusive) - or -1 to clear to end of buffer. + {buffer} Buffer handle, or 0 for current buffer + {name} Variable name + {value} Variable value *nvim_buf_set_virtual_text()* nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) @@ -2025,33 +2049,26 @@ 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(). +============================================================================== +Window Functions *api-window* - If there is no virtual text associated with the given line, an - empty list is returned. +nvim_win_close({window}, {force}) *nvim_win_close()* + Closes the window (like |:close| with a |window-ID|). 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 + {window} Window handle, or 0 for current window + {force} Behave like `:close!` The last window of a + buffer with unwritten changes can be closed. The + buffer will become hidden, even if 'hidden' is + not set. +nvim_win_del_var({window}, {name}) *nvim_win_del_var()* + Removes a window-scoped (w:) variable -============================================================================== -Window Functions *api-window* + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Variable name nvim_win_get_buf({window}) *nvim_win_get_buf()* Gets the current buffer in a window @@ -2062,12 +2079,19 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()* Return: ~ Buffer handle -nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* - Sets the current buffer in a window, without side-effects +nvim_win_get_config({window}) *nvim_win_get_config()* + Gets window configuration. + + The returned value may be given to |nvim_open_win()|. + + `relative` is empty for normal windows. Parameters: ~ {window} Window handle, or 0 for current window - {buffer} Buffer handle + + Return: ~ + Map defining the window configuration, see + |nvim_open_win()| nvim_win_get_cursor({window}) *nvim_win_get_cursor()* Gets the (1,0)-indexed cursor position in the window. @@ -2079,14 +2103,6 @@ nvim_win_get_cursor({window}) *nvim_win_get_cursor()* Return: ~ (row, col) tuple -nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* - Sets the (1,0)-indexed cursor position in the window. - |api-indexing| - - Parameters: ~ - {window} Window handle, or 0 for current window - {pos} (row, col) tuple representing the new position - nvim_win_get_height({window}) *nvim_win_get_height()* Gets the window height @@ -2096,55 +2112,14 @@ nvim_win_get_height({window}) *nvim_win_get_height()* Return: ~ Height as a count of rows -nvim_win_set_height({window}, {height}) *nvim_win_set_height()* - Sets the window height. This will only succeed if the screen - is split horizontally. - - Parameters: ~ - {window} Window handle, or 0 for current window - {height} Height as a count of rows - -nvim_win_get_width({window}) *nvim_win_get_width()* - Gets the window width - - Parameters: ~ - {window} Window handle, or 0 for current window - - Return: ~ - Width as a count of columns - -nvim_win_set_width({window}, {width}) *nvim_win_set_width()* - Sets the window width. This will only succeed if the screen is - split vertically. - - Parameters: ~ - {window} Window handle, or 0 for current window - {width} Width as a count of columns - -nvim_win_get_var({window}, {name}) *nvim_win_get_var()* - Gets a window-scoped (w:) variable +nvim_win_get_number({window}) *nvim_win_get_number()* + Gets the window number Parameters: ~ {window} Window handle, or 0 for current window - {name} Variable name Return: ~ - Variable value - -nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* - Sets a window-scoped (w:) variable - - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Variable name - {value} Variable value - -nvim_win_del_var({window}, {name}) *nvim_win_del_var()* - Removes a window-scoped (w:) variable - - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Variable name + Window number nvim_win_get_option({window}, {name}) *nvim_win_get_option()* Gets a window option value @@ -2156,15 +2131,6 @@ nvim_win_get_option({window}, {name}) *nvim_win_get_option()* Return: ~ Option value -nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()* - Sets a window option value. Passing 'nil' as value deletes the - option(only works if there's a global fallback) - - Parameters: ~ - {window} Window handle, or 0 for current window - {name} Option name - {value} Option value - nvim_win_get_position({window}) *nvim_win_get_position()* Gets the window position in display cells. First position is zero. @@ -2184,14 +2150,24 @@ nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()* Return: ~ Tabpage that contains the window -nvim_win_get_number({window}) *nvim_win_get_number()* - Gets the window number +nvim_win_get_var({window}, {name}) *nvim_win_get_var()* + Gets a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window + {name} Variable name Return: ~ - Window number + Variable value + +nvim_win_get_width({window}) *nvim_win_get_width()* + Gets the window width + + Parameters: ~ + {window} Window handle, or 0 for current window + + Return: ~ + Width as a count of columns nvim_win_is_valid({window}) *nvim_win_is_valid()* Checks if a window is valid @@ -2202,6 +2178,13 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()* Return: ~ true if the window is valid, false otherwise +nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* + Sets the current buffer in a window, without side-effects + + Parameters: ~ + {window} Window handle, or 0 for current window + {buffer} Buffer handle + nvim_win_set_config({window}, {config}) *nvim_win_set_config()* Configures window layout. Currently only for floating and external windows (including changing a split window to those @@ -2219,67 +2202,76 @@ nvim_win_set_config({window}, {config}) *nvim_win_set_config()* See also: ~ |nvim_open_win()| -nvim_win_get_config({window}) *nvim_win_get_config()* - Gets window configuration. +nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* + Sets the (1,0)-indexed cursor position in the window. + |api-indexing| - The returned value may be given to |nvim_open_win()|. + Parameters: ~ + {window} Window handle, or 0 for current window + {pos} (row, col) tuple representing the new position - `relative` is empty for normal windows. +nvim_win_set_height({window}, {height}) *nvim_win_set_height()* + Sets the window height. This will only succeed if the screen + is split horizontally. Parameters: ~ {window} Window handle, or 0 for current window + {height} Height as a count of rows - Return: ~ - Map defining the window configuration, see - |nvim_open_win()| +nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()* + Sets a window option value. Passing 'nil' as value deletes the + option(only works if there's a global fallback) -nvim_win_close({window}, {force}) *nvim_win_close()* - Closes the window (like |:close| with a |window-ID|). + Parameters: ~ + {window} Window handle, or 0 for current window + {name} Option name + {value} Option value + +nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* + Sets a window-scoped (w:) variable Parameters: ~ {window} Window handle, or 0 for current window - {force} Behave like `:close!` The last window of a - buffer with unwritten changes can be closed. The - buffer will become hidden, even if 'hidden' is - not set. + {name} Variable name + {value} Variable value + +nvim_win_set_width({window}, {width}) *nvim_win_set_width()* + Sets the window width. This will only succeed if the screen is + split vertically. + + Parameters: ~ + {window} Window handle, or 0 for current window + {width} Width as a count of columns ============================================================================== Tabpage Functions *api-tabpage* -nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* - Gets the windows in a tabpage +nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* + Removes a tab-scoped (t:) variable Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name - Return: ~ - List of windows in `tabpage` - -nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* - Gets a tab-scoped (t:) variable +nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* + Gets the tabpage number Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage - {name} Variable name Return: ~ - Variable value + Tabpage number -nvim_tabpage_set_var({tabpage}, {name}, {value}) *nvim_tabpage_set_var()* - Sets a tab-scoped (t:) variable +nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* + Gets a tab-scoped (t:) variable Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage {name} Variable name - {value} Variable value - -nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* - Removes a tab-scoped (t:) variable - Parameters: ~ - {tabpage} Tabpage handle, or 0 for current tabpage - {name} Variable name + Return: ~ + Variable value nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* Gets the current window in a tabpage @@ -2290,23 +2282,31 @@ nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* Return: ~ Window handle -nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* - Gets the tabpage number +nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* + Checks if a tabpage is valid Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage Return: ~ - Tabpage number + true if the tabpage is valid, false otherwise -nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* - Checks if a tabpage is valid +nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* + Gets the windows in a tabpage Parameters: ~ {tabpage} Tabpage handle, or 0 for current tabpage Return: ~ - true if the tabpage is valid, false otherwise + List of windows in `tabpage` + +nvim_tabpage_set_var({tabpage}, {name}, {value}) *nvim_tabpage_set_var()* + Sets a tab-scoped (t:) variable + + Parameters: ~ + {tabpage} Tabpage handle, or 0 for current tabpage + {name} Variable name + {value} Variable value ============================================================================== @@ -2335,10 +2335,17 @@ nvim_ui_detach() *nvim_ui_detach()* Removes the client from the list of UIs. |nvim_list_uis()| -nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* - TODO: Documentation +nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* + Tells Nvim the number of elements displaying in the popumenu, + to decide and movement. + + Parameters: ~ + {height} Popupmenu height, must be greater than zero. nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* + TODO: Documentation + +nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* TODO: Documentation *nvim_ui_try_resize_grid()* @@ -2354,11 +2361,4 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) {width} The new requested width. {height} The new requested height. -nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* - Tells Nvim the number of elements displaying in the popumenu, - to decide and movement. - - Parameters: ~ - {height} Popupmenu height, must be greater than zero. - vim:tw=78:ts=8:ft=help:norl: -- cgit From b112fe828fd2457692f556626d7657615e53cb0b Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 31 Dec 2019 06:52:14 -0800 Subject: gen_vimdoc.py: generate LSP docs --- runtime/doc/api.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 7d45330b66..f8fdd64a9b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -569,7 +569,8 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* occurred, the values from all preceding calls will still be returned. -nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()* + *nvim_call_dict_function()* +nvim_call_dict_function({dict}, {fn}, {args}) Calls a VimL |Dictionary-function| with the given arguments. On execution error: fails with VimL error, does not update @@ -1878,7 +1879,8 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* Return: ~ Variable value -nvim_buf_get_virtual_text({buffer}, {lnum}) *nvim_buf_get_virtual_text()* + *nvim_buf_get_virtual_text()* +nvim_buf_get_virtual_text({buffer}, {lnum}) Get the virtual text (annotation) for a buffer line. The virtual text is returned as list of lists, whereas the @@ -2300,7 +2302,8 @@ nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* Return: ~ List of windows in `tabpage` -nvim_tabpage_set_var({tabpage}, {name}, {value}) *nvim_tabpage_set_var()* + *nvim_tabpage_set_var()* +nvim_tabpage_set_var({tabpage}, {name}, {value}) Sets a tab-scoped (t:) variable Parameters: ~ -- cgit From 92316849863bb2661ee5b4bb284f56163fed27ad Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 12 Jan 2020 23:41:55 -0800 Subject: doc [ci skip] #11656 --- runtime/doc/api.txt | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index f8fdd64a9b..39b6c6417d 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -183,21 +183,17 @@ External programs (clients) can use the metadata to discover the API, using any of these approaches: 1. Connect to a running Nvim instance and call |nvim_get_api_info()| via - msgpack-rpc. This is best for clients written in dynamic languages which + msgpack-RPC. This is best for clients written in dynamic languages which can define functions at runtime. - 2. Start Nvim with the |--api-info| option. Useful for clients written in - statically-compiled languages. - - 3. Use the |api_info()| Vimscript function. - -Example: To get a human-readable list of API functions: > - :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') -< -Example: To get a formatted dump of the API using python (requires the -"pyyaml" and "msgpack-python" modules): > - nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' + 2. Start Nvim with |--api-info|. Useful for statically-compiled clients. + Example (requires Python "pyyaml" and "msgpack-python" modules): > + nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' < + 3. Use the |api_info()| Vimscript function. > + :lua print(vim.inspect(vim.fn.api_info())) +< Example using |filter()| to exclude non-deprecated API functions: > + :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') ============================================================================== API contract *api-contract* -- cgit From 630ec6cfb8670607ddfc67dd4e56e98c17746ca6 Mon Sep 17 00:00:00 2001 From: Yatao Li Date: Mon, 24 Feb 2020 16:40:58 +0800 Subject: API/UI: Allow UI to set PUM position and size, and pass the position to CompleteChanged --- runtime/doc/api.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 39b6c6417d..c5ccf35c8e 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -2341,6 +2341,22 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* Parameters: ~ {height} Popupmenu height, must be greater than zero. + *nvim_ui_pum_set_bounds()* +nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) + + Tells Nvim the geometry of the popumenu, to align floating + windows with an external popup menu. Note that this method + is not to be confused with |nvim_ui_pum_set_height()|, which + sets the number of visible items in the popup menu, while + this function sets the bounding box of the popup menu, + including visual decorations such as boarders and sliders. + + Parameters: ~ + {width} Popupmenu width, must be greater than zero. + {height} Popupmenu height, must be greater than zero. + {row} Popupmenu row, must be greater or equal to zero. + {height} Popupmenu height, must be greater or equal to zero. + nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation -- cgit From 9c85caa390ccf6295233c4201a60ccfa66417816 Mon Sep 17 00:00:00 2001 From: Yatao Li Date: Tue, 3 Mar 2020 17:43:02 +0800 Subject: ui_pum_get_pos: return internal pum position if external pum pos not found --- runtime/doc/api.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c5ccf35c8e..a2e0c56f85 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -2352,10 +2352,10 @@ nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) including visual decorations such as boarders and sliders. Parameters: ~ - {width} Popupmenu width, must be greater than zero. - {height} Popupmenu height, must be greater than zero. - {row} Popupmenu row, must be greater or equal to zero. - {height} Popupmenu height, must be greater or equal to zero. + {width} Popupmenu width. + {height} Popupmenu height. + {row} Popupmenu row. + {height} Popupmenu height. nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation -- cgit From 52cd8bf507d44bd5bad3f9c915ef6def7b6623c4 Mon Sep 17 00:00:00 2001 From: Hirokazu Hata Date: Tue, 19 May 2020 14:26:17 +0900 Subject: doc: fix vim.api.nvim_buf_attach callback arguments --- runtime/doc/api.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index a2e0c56f85..fdabb0da50 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1612,6 +1612,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* {opts} Optional parameters. • on_lines: Lua callback invoked on change. Return`true`to detach. Args: + • the string "lines" • buffer handle • b:changedtick • first line that changed (zero-indexed) @@ -1626,11 +1627,13 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • on_changedtick: Lua callback invoked on changedtick increment without text change. Args: + • the string "changedtick" • buffer handle • b:changedtick • on_detach: Lua callback invoked on detach. Args: + • the string "detach" • buffer handle • utf_sizes: include UTF-32 and UTF-16 size -- cgit From 2844cd54dab2893a0baa0464e8de0a01f1048b05 Mon Sep 17 00:00:00 2001 From: Anmol Sethi Date: Wed, 1 Jul 2020 21:57:03 -0400 Subject: docs: Describe how to escape keycodes with nvim_feedkeys (#12484) Closes #12297 --- runtime/doc/api.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index fdabb0da50..67260904a6 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -729,6 +729,15 @@ 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 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. + + Example: > + :let key = nvim_replace_termcodes("", v:true, v:false, v:true) + :call nvim_feedkeys(key, 'n', v:true) +< + Parameters: ~ {keys} to be typed {mode} behavior flags, see |feedkeys()| -- cgit From 7b529e7912517af078e005dd7b06b3d042be9cb7 Mon Sep 17 00:00:00 2001 From: TJ DeVries Date: Thu, 2 Jul 2020 07:09:17 -0400 Subject: doc: fix scripts and regenerate (#12506) * Fix some small doc issues * doc: fixup * doc: fixup * Fix lint and rebase * Remove bad advice * Ugh, stupid mpack files... * Don't let people include these for now until they specifically want to * Prevent duplicate tag --- runtime/doc/api.txt | 101 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 68 insertions(+), 33 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 67260904a6..ea3a8242ae 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -475,6 +475,9 @@ created for extmark changes. ============================================================================== Global Functions *api-global* +nvim__get_lib_dir() *nvim__get_lib_dir()* + TODO: Documentation + nvim__id({obj}) *nvim__id()* Returns object given as argument. @@ -526,7 +529,8 @@ nvim__id_float({flt}) *nvim__id_float()* nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* TODO: Documentation -nvim__put_attr({id}, {c0}, {c1}) *nvim__put_attr()* + *nvim__put_attr()* +nvim__put_attr({id}, {start_row}, {start_col}, {end_row}, {end_col}) Set attrs in nvim__buf_set_lua_hl callbacks TODO(bfredl): This is rather pedestrian. The final interface @@ -612,7 +616,8 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Parameters: ~ {listed} Sets 'buflisted' {scratch} Creates a "throwaway" |scratch-buffer| for - temporary work (always 'nomodified') + temporary work (always 'nomodified'). Also sets + 'nomodeline' on the buffer. Return: ~ Buffer handle, or 0 on error @@ -938,6 +943,23 @@ nvim_get_proc_children({pid}) *nvim_get_proc_children()* Return: ~ Array of child process ids, empty if process not found. +nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* + Find files in runtime directories + + 'name' can contain wildcards. For example + nvim_get_runtime_file("colors/*.vim", true) will return all + color scheme files. + + It is not an error to not find any files. An empty array is + returned then. + + Parameters: ~ + {name} pattern of files to search for + {all} whether to return all matches or only the first + + Return: ~ + list of absolute paths to the found files + nvim_get_var({name}) *nvim_get_var()* Gets a global (g:) variable. @@ -1526,6 +1548,9 @@ nvim_unsubscribe({event}) *nvim_unsubscribe()* ============================================================================== Buffer Functions *api-buffer* + +For more information on buffers, see |buffers|. + Unloaded Buffers:~ Buffers may be unloaded by the |:bunload| command or the @@ -1539,6 +1564,12 @@ affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. + *nvim__buf_add_decoration()* +nvim__buf_add_decoration({buffer}, {ns_id}, {hl_group}, {start_row}, + {start_col}, {end_row}, {end_col}, + {virt_text}) + TODO: Documentation + *nvim__buf_redraw_range()* nvim__buf_redraw_range({buffer}, {first}, {last}) TODO: Documentation @@ -1559,7 +1590,7 @@ nvim__buf_stats({buffer}) *nvim__buf_stats()* TODO: Documentation *nvim_buf_add_highlight()* -nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, +nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, {col_start}, {col_end}) Adds a highlight to buffer. @@ -1756,8 +1787,8 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) 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], {}) + nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) + nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {}) < If `end` is less than `start` , traversal works backwards. @@ -1766,18 +1797,18 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) 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)) + 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: ~ @@ -1888,7 +1919,7 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* Variable value *nvim_buf_get_virtual_text()* -nvim_buf_get_virtual_text({buffer}, {lnum}) +nvim_buf_get_virtual_text({buffer}, {line}) Get the virtual text (annotation) for a buffer line. The virtual text is returned as list of lists, whereas the @@ -2022,7 +2053,8 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* {value} Variable value *nvim_buf_set_virtual_text()* -nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) +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 @@ -2346,28 +2378,31 @@ nvim_ui_detach() *nvim_ui_detach()* Removes the client from the list of UIs. |nvim_list_uis()| -nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* - Tells Nvim the number of elements displaying in the popumenu, - to decide and movement. - - Parameters: ~ - {height} Popupmenu height, must be greater than zero. - *nvim_ui_pum_set_bounds()* nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) + Tells Nvim the geometry of the popumenu, to align floating + windows with an external popup menu. - Tells Nvim the geometry of the popumenu, to align floating - windows with an external popup menu. Note that this method - is not to be confused with |nvim_ui_pum_set_height()|, which - sets the number of visible items in the popup menu, while - this function sets the bounding box of the popup menu, - including visual decorations such as boarders and sliders. + Note that this method is not to be confused with + |nvim_ui_pum_set_height()|, which sets the number of visible + items in the popup menu, while this function sets the bounding + box of the popup menu, including visual decorations such as + boarders and sliders. Floats need not use the same font size, + nor be anchored to exact grid corners, so one can set + floating-point numbers to the popup menu geometry. Parameters: ~ {width} Popupmenu width. {height} Popupmenu height. {row} Popupmenu row. - {height} Popupmenu height. + {col} Popupmenu height. + +nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* + Tells Nvim the number of elements displaying in the popumenu, + to decide and movement. + + Parameters: ~ + {height} Popupmenu height, must be greater than zero. nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation -- cgit